rack-attack 4.3.1 → 5.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 62911565ba358aadd130a8edf862d1f3ca57786d
-  data.tar.gz: 55876d8afb3bed309bb09a5b1fae357c8d5cdf10
+SHA256:
+  metadata.gz: e666812691cc414692f7125979f0b152a9111ccee075e65b811fa4a6d8770daa
+  data.tar.gz: 3e8caba79f7ad09d4999cce6358de9cc29b815dee3c9f9c5adbf12763c764656
 SHA512:
-  metadata.gz: b54245dad4b5101ce8364da45654d650bfe86c2f4e3c85d48e3923b7ca8a31ad5ec61e3938745dedefba3fd117447e522a4207145b086eccf86bf14ba1696643
-  data.tar.gz: 57063639a9c9d6e3884b1a89cbfce044fefebe7dcb4a95f1e025e260db75490a05447d4e7294060aa55531b55d567b9763101debb2119a690c8760b0b94787ec
+  metadata.gz: f630c0cd1a34bd588e616653a2e6795e2ec6baafc0e0df8b489e6aa451cf47fb64065447fb3ceb2b029a51d87a0393d6d44cea02e58423626ea46165531f7da3
+  data.tar.gz: 22efc414db06b0a1bbbf8e6d34a3e0d0ead64f1832f48dc30af7ec0a374ef215d53cacf0a8e95c842bff0af84df0939f27820e4668c739eb8db3c51ebba4088e

data/README.md

@@ -1,198 +1,240 @@
-# Rack::Attack!!!
-*Rack middleware for blocking & throttling abusive requests*
-
-Rack::Attack is a rack middleware to protect your web app from bad clients.
-It allows *whitelisting*, *blacklisting*, *throttling*, and *tracking* based on arbitrary properties of the request.
+# Rack::Attack
 
-Throttle and fail2ban state is stored in a configurable cache (e.g. `Rails.cache`), presumably backed by memcached or redis ([at least gem v3.0.0](https://rubygems.org/gems/redis)).
+*Rack middleware for blocking & throttling abusive requests*
 
-See the [Backing & Hacking blog post](http://www.kickstarter.com/backing-and-hacking/rack-attack-protection-from-abusive-clients) introducing Rack::Attack.
+Protect your Rails and Rack apps from bad clients. Rack::Attack lets you easily decide when to *allow*, *block* and *throttle* based on properties of the request.
 
-[![Gem Version](https://badge.fury.io/rb/rack-attack.png)](http://badge.fury.io/rb/rack-attack)
-[![Build Status](https://travis-ci.org/kickstarter/rack-attack.png?branch=master)](https://travis-ci.org/kickstarter/rack-attack)
-[![Code Climate](https://codeclimate.com/github/kickstarter/rack-attack.png)](https://codeclimate.com/github/kickstarter/rack-attack)
+See the [Backing & Hacking blog post](https://www.kickstarter.com/backing-and-hacking/rack-attack-protection-from-abusive-clients) introducing Rack::Attack.
 
+[![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)
 
 ## Getting started
 
-Install the [rack-attack](http://rubygems.org/gems/rack-attack) gem; or add it to your Gemfile with bundler:
+### 1. Installing
+
+Add this line to your application's Gemfile:
 
 ```ruby
 # In your Gemfile
+
 gem 'rack-attack'
 ```
-Tell your app to use the Rack::Attack middleware.
-For Rails 3+ apps:
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install rack-attack
+
+### 2. Plugging into the application
+
+Then tell your ruby web application to use rack-attack as a middleware.
+
+a) For __rails__ applications:
 
 ```ruby
 # In config/application.rb
+
 config.middleware.use Rack::Attack
 ```
 
-Or for Rackup files:
+b) For __rack__ applications:
 
 ```ruby
 # In config.ru
+
+require "rack/attack"
 use Rack::Attack
 ```
 
-Add a `rack-attack.rb` file to `config/initializers/`:
-```ruby
-# In config/initializers/rack-attack.rb
-class Rack::Attack
-  # your custom configuration...
-end
-```
+__IMPORTANT__: By default, rack-attack won't perform any blocking or throttling, until you specifically tell it what to protect against by configuring some rules.
+
+## 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)
 
-Optionally configure the cache store for throttling or fail2ban filtering:
+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.
 
-```ruby
-Rack::Attack.cache.store = ActiveSupport::Cache::MemoryStore.new # defaults to Rails.cache
-```
+### Safelisting
 
-Note that `Rack::Attack.cache` is only used for throttling and fail2ban filtering; not blacklisting & whitelisting. Your cache store must implement `increment` and `write` like [ActiveSupport::Cache::Store](http://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html).
+Safelists have the most precedence, so any request matching a safelist would be allowed despite matching any number of blocklists or throttles.
 
-## How it works
+#### `safelist_ip(ip_address_string)`
 
-The Rack::Attack middleware compares each request against *whitelists*, *blacklists*, *throttles*, and *tracks* that you define. There are none by default.
+E.g.
 
- * If the request matches any **whitelist**, it is allowed.
- * Otherwise, if the request matches any **blacklist**, it is blocked.
- * 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.
+```ruby
+# config/initializers/rack_attack.rb (for rails app)
 
-The algorithm is actually more concise in code: See [Rack::Attack.call](https://github.com/kickstarter/rack-attack/blob/master/lib/rack/attack.rb):
+Rack::Attack.safelist_ip("5.6.7.8")
+```
+
+#### `safelist_ip(ip_subnet_string)`
+
+E.g.
 
 ```ruby
-def call(env)
-  req = Rack::Attack::Request.new(env)
+# config/initializers/rack_attack.rb (for rails app)
 
-  if whitelisted?(req)
-    @app.call(env)
-  elsif blacklisted?(req)
-    self.class.blacklisted_response.call(env)
-  elsif throttled?(req)
-    self.class.throttled_response.call(env)
-  else
-    tracked?(req)
-    @app.call(env)
-  end
-end
+Rack::Attack.safelist_ip("5.6.7.0/24")
 ```
 
-Note: `Rack::Attack::Request` is just a subclass of `Rack::Attack` 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).
+#### `safelist(name, &block)`
 
-## About Tracks
+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.
 
-`Rack::Attack.track` doesn't affect request processing. Tracks are an easy way to log and measure requests matching arbitrary attributes.
+The request object is a [Rack::Request](http://www.rubydoc.info/gems/rack/Rack/Request).
 
-## Usage
+E.g.
 
-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://www.rubydoc.info/gems/rack/Rack/Request) object is passed to the block (named 'req' in the examples).
+```ruby
+# config/initializers/rack_attack.rb (for rails apps)
 
-### Whitelists
+# Provided that trusted users use an HTTP request header named APIKey
+Rack::Attack.safelist("mark any authenticated access safe") do |request|
+  # Requests are allowed if the return value is truthy
+  request.env["APIKey"] == "secret-string"
+end
 
-```ruby
 # Always allow requests from localhost
-# (blacklist & throttles are skipped)
-Rack::Attack.whitelist('allow from localhost') do |req|
+# (blocklist & throttles are skipped)
+Rack::Attack.safelist('allow from localhost') do |req|
   # Requests are allowed if the return value is truthy
   '127.0.0.1' == req.ip || '::1' == req.ip
 end
 ```
 
-### Blacklists
+### Blocking
+
+#### `blocklist_ip(ip_address_string)`
+
+E.g.
+
+```ruby
+# config/initializers/rack_attack.rb (for rails apps)
+
+Rack::Attack.blocklist_ip("1.2.3.4")
+```
+
+#### `blocklist_ip(ip_subnet_string)`
+
+E.g.
+
+```ruby
+# config/initializers/rack_attack.rb (for rails apps)
+
+Rack::Attack.blocklist_ip("1.2.0.0/16")
+```
+
+#### `blocklist(name, &block)`
+
+Name your custom blocklist and make your ruby-block argument return a truthy value if you want the request to be blocked, and falsy otherwise.
+
+The request object is a [Rack::Request](http://www.rubydoc.info/gems/rack/Rack/Request).
+
+E.g.
 
 ```ruby
-# Block requests from 1.2.3.4
-Rack::Attack.blacklist('block 1.2.3.4') do |req|
+# config/initializers/rack_attack.rb (for rails apps)
+
+Rack::Attack.blocklist("block all access to admin") do |request|
   # Requests are blocked if the return value is truthy
-  '1.2.3.4' == req.ip
+  request.path.start_with?("/admin")
 end
 
-# Block logins from a bad user agent
-Rack::Attack.blacklist('block bad UA logins') do |req|
+Rack::Attack.blocklist('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.  For multiple filters, be sure to put each filter in a separate blacklist and use a unique discriminator for each fail2ban filter.
+`Fail2Ban.filter` can be used within a blocklist to block all requests from misbehaving clients.
+This pattern is inspired by [fail2ban](https://www.fail2ban.org/wiki/index.php/Main_Page).
+See the [fail2ban documentation](https://www.fail2ban.org/wiki/index.php/MANUAL_0_8#Jail_Options) for more details on
+how the parameters work.  For multiple filters, be sure to put each filter in a separate blocklist and use a unique discriminator for each fail2ban filter.
+
+Fail2ban state is stored in a [configurable cache](#cache-store-configuration) (which defaults to `Rails.cache` if present).
 
 ```ruby
 # Block suspicious requests for '/etc/password' or wordpress specific paths.
 # After 3 blocked requests in 10 minutes, block all requests from that IP for 5 minutes.
-Rack::Attack.blacklist('fail2ban pentesters') do |req|
+Rack::Attack.blocklist('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("pentesters-#{req.ip}", :maxretry => 3, :findtime => 10.minutes, :bantime => 5.minutes) do
+  Rack::Attack::Fail2Ban.filter("pentesters-#{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} || 
+    CGI.unescape(req.query_string) =~ %r{/etc/passwd} ||
     req.path.include?('/etc/passwd') ||
-    req.path.include?('wp-admin') || 
+    req.path.include?('wp-admin') ||
     req.path.include?('wp-login')
-    
+
   end
 end
 ```
 
-Note that `Fail2Ban` filters are not automatically scoped to the blacklist, so when using multiple filters in an application the scoping must be added to the discriminator e.g. `"pentest:#{req.ip}"`.
+Note that `Fail2Ban` filters are not automatically scoped to the blocklist, so when using multiple filters in an application the scoping must be added to the discriminator e.g. `"pentest:#{req.ip}"`.
 
 #### Allow2Ban
+
 `Allow2Ban.filter` works the same way as the `Fail2Ban.filter` except that it *allows* requests from misbehaving
 clients until such time as they reach maxretry at which they are cut off as per normal.
+
+Allow2ban state is stored in a [configurable cache](#cache-store-configuration) (which defaults to `Rails.cache` if present).
+
 ```ruby
 # Lockout IP addresses that are hammering your login page.
 # After 20 requests in 1 minute, block all requests from that IP for 1 hour.
-Rack::Attack.blacklist('allow2ban login scrapers') do |req|
+Rack::Attack.blocklist('allow2ban login scrapers') do |req|
   # `filter` returns false value if request is to your login page (but still
   # increments the count) so request below the limit are not blocked until
   # they hit the limit.  At that point, filter will return true and block.
-  Rack::Attack::Allow2Ban.filter(req.ip, :maxretry => 20, :findtime => 1.minute, :bantime => 1.hour) do
+  Rack::Attack::Allow2Ban.filter(req.ip, maxretry: 20, findtime: 1.minute, bantime: 1.hour) do
     # The count for the IP is incremented if the return value is truthy.
     req.path == '/login' and req.post?
   end
 end
 ```
 
+### Throttling
+
+Throttle state is stored in a [configurable cache](#cache-store-configuration) (which defaults to `Rails.cache` if present).
+
+#### `throttle(name, options, &block)`
 
-### Throttles
+Name your custom throttle, provide `limit` and `period` as options, and make your ruby-block argument return the __discriminator__. This discriminator is how you tell rack-attack whether you're limiting per IP address, per user email or any other.
+
+The request object is a [Rack::Request](http://www.rubydoc.info/gems/rack/Rack/Request).
+
+E.g.
 
 ```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
-  # is incremented and compared with the limit. In this case:
-  #   "rack::attack:#{Time.now.to_i/1.second}:req/ip:#{req.ip}"
-  #
-  # If falsy, the cache key is neither incremented nor checked.
-
-  req.ip
+# config/initializers/rack_attack.rb (for rails apps)
+
+Rack::Attack.throttle("requests by ip", limit: 5, period: 2) do |request|
+  request.ip
 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.params['email'] if req.path == '/login' && req.post?
+Rack::Attack.throttle('limit logins per email', limit: 6, period: 60) do |req|
+  if req.path == '/login' && req.post?
+    req.params['email']
+  end
 end
 
 # You can also set a limit and period using a proc. For instance, after
 # Rack::Auth::Basic has authenticated the user:
-limit_proc = proc {|req| req.env["REMOTE_USER"] == "admin" ? 100 : 1}
-period_proc = proc {|req| req.env["REMOTE_USER"] == "admin" ? 1.second : 1.minute}
-Rack::Attack.throttle('req/ip', :limit => limit_proc, :period => period_proc) do |req|
-  req.ip
+limit_proc = proc { |req| req.env["REMOTE_USER"] == "admin" ? 100 : 1 }
+period_proc = proc { |req| req.env["REMOTE_USER"] == "admin" ? 1 : 60 }
+
+Rack::Attack.throttle('request per ip', limit: limit_proc, period: period_proc) do |request|
+  request.ip
 end
 ```
 
@@ -205,7 +247,7 @@ Rack::Attack.track("special_agent") do |req|
 end
 
 # Supports optional limit and period, triggers the notification only when the limit is reached.
-Rack::Attack.track("special_agent", :limit => 6, :period => 60.seconds) do |req|
+Rack::Attack.track("special_agent", limit: 6, period: 60) do |req|
   req.user_agent == "SpecialAgent"
 end
 
@@ -218,35 +260,67 @@ ActiveSupport::Notifications.subscribe("rack.attack") do |name, start, finish, r
 end
 ```
 
-## Responses
+### Cache store configuration
+
+Throttle, allow2ban and fail2ban state is stored in a configurable cache (which defaults to `Rails.cache` if present), presumably backed by memcached or redis ([at least gem v3.0.0](https://rubygems.org/gems/redis)).
+
+```ruby
+Rack::Attack.cache.store = ActiveSupport::Cache::MemoryStore.new # defaults to Rails.cache
+```
+
+Note that `Rack::Attack.cache` is only used for throttling, allow2ban and fail2ban filtering; not blocklisting and safelisting. Your cache store must implement `increment` and `write` like [ActiveSupport::Cache::Store](http://api.rubyonrails.org/classes/ActiveSupport/Cache/Store.html).
+
+## Customizing 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).
+Customize the response of blocklisted and throttled requests using an object that adheres to the [Rack app interface](http://www.rubydoc.info/github/rack/rack/file/SPEC).
 
 ```ruby
-Rack::Attack.blacklisted_response = lambda do |env|
+Rack::Attack.blocklisted_response = lambda do |env|
   # Using 503 because it may make attacker think that they have successfully
-  # DOSed the site. Rack::Attack returns 403 for blacklists by default
+  # DOSed the site. Rack::Attack returns 403 for blocklists by default
   [ 503, {}, ['Blocked']]
 end
 
 Rack::Attack.throttled_response = lambda do |env|
-  # name and other data about the matched throttle
-  body = [
-    env['rack.attack.matched'],
-    env['rack.attack.match_type'],
-    env['rack.attack.match_data']
-  ].inspect
+  # NB: you have access to the name and other data about the matched throttle
+  #  env['rack.attack.matched'],
+  #  env['rack.attack.match_type'],
+  #  env['rack.attack.match_data'],
+  #  env['rack.attack.match_discriminator']
 
   # Using 503 because it may make attacker think that they have successfully
   # DOSed the site. Rack::Attack returns 429 for throttling by default
-  [ 503, {}, [body]]
+  [ 503, {}, ["Server Error\n"]]
+end
+```
+
+### X-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:
+
+```ruby
+Rack::Attack.throttled_response = lambda do |env|
+  match_data = env['rack.attack.match_data']
+  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
+  }
+
+  [ 429, headers, ["Throttled\n"]]
 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 }
+request.env['rack.attack.throttle_data'][name] # => { :count => n, :period => p, :limit => l, :epoch_time => t }
 ```
 
 ## Logging & Instrumentation
@@ -261,6 +335,43 @@ ActiveSupport::Notifications.subscribe('rack.attack') do |name, start, finish, r
 end
 ```
 
+## How it works
+
+The Rack::Attack middleware compares each request against *safelists*, *blocklists*, *throttles*, and *tracks* that you define. There are none by default.
+
+ * If the request matches any **safelist**, it is allowed.
+ * Otherwise, if the request matches any **blocklist**, it is blocked.
+ * 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):
+
+```ruby
+def call(env)
+  req = Rack::Attack::Request.new(env)
+
+  if safelisted?(req)
+    @app.call(env)
+  elsif blocklisted?(req)
+    self.class.blocklisted_response.call(env)
+  elsif throttled?(req)
+    self.class.throttled_response.call(env)
+  else
+    tracked?(req)
+    @app.call(env)
+  end
+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).
+
+### About Tracks
+
+`Rack::Attack.track` doesn't affect request processing. Tracks are an easy way to log and measure requests matching arbitrary attributes.
+
+
 ## Testing
 
 A note on developing and testing apps using Rack::Attack - if you are using throttling in particular, you will
@@ -274,10 +385,10 @@ but it depends on how many checks you've configured, and how long they take.
 Throttles usually require a network roundtrip to your cache server(s),
 so try to keep the number of throttle checks per request low.
 
-If a request is blacklisted or throttled, the response is a very simple Rack response.
+If a request is blocklisted or throttled, the response is a very simple Rack response.
 A single typical ruby web server thread can block several hundred requests per second.
 
-Rack::Attack complements tools like `iptables` and nginx's [limit_conn_zone module](http://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone).
+Rack::Attack complements tools like `iptables` and nginx's [limit_conn_zone module](https://nginx.org/en/docs/http/ngx_http_limit_conn_module.html#limit_conn_zone).
 
 ## Motivation
 
@@ -291,9 +402,15 @@ less on short-term, one-off hacks to block a particular attack.
 
 ## Contributing
 
-Pull requests and issues are greatly appreciated. This project is intended to be
-a safe, welcoming space for collaboration, and contributors are expected to
-adhere to the [Code of Conduct](CODE_OF_CONDUCT.md).
+Check out the [Contributing guide](CONTRIBUTING.md).
+
+## Code of Conduct
+
+This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## Development setup
+
+Check out the [Development guide](docs/development.md).
 
 ## Mailing list
 
@@ -304,6 +421,6 @@ New releases of Rack::Attack are announced on
 
 ## License
 
-Copyright Kickstarter, Inc.
+Copyright Kickstarter, PBC.
 
-Released under an [MIT License](http://opensource.org/licenses/MIT).
+Released under an [MIT License](https://opensource.org/licenses/MIT).