Rack::Attack!!!

A DSL for blocking & throttling abusive clients

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.

Throttle state is stored in a configurable cache (e.g. Rails.cache), presumably backed by memcached or redis.

Installation

Install the rack-attack gem; or add it to you Gemfile with bundler:

# In your Gemfile
gem '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 for Rackup files:

# In config.ru
use Rack::Attack

Optionally configure the cache store for throttling:

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.

How it works

The Rack::Attack middleware compares each request against whitelists, blacklists, throttles, and tracks that you define. There are none by default.

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 the throttle 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:

def call(env)
  req = Rack::Request.new(env)

  if whitelisted?(req)
    @app.call(env)
  elsif blacklisted?(req)
    blacklisted_response[env]
  elsif throttled?(req)
    throttled_response[env]
  else
    tracked?(req)
    @app.call(env)
  end
end

About Tracks

Rack::Attack.track doesn't affect request processing. Tracks are an easy way to log and measure requests matching arbitrary attributes.

Usage

Define whitelists, blacklists, throttles, and tracks as blocks that return truthy values if matched, falsy otherwise. A Rack::Request object is passed to the block (named 'req' in the examples).

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

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.path == '/login' && req.post? && 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 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
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.path == '/login' && req.post? && req.params['email']
end

Tracks

# Track requests from a special user agent
Rack::Attack.track("special_agent") do |req|
  req.user_agent == "SpecialAgent"
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
    Rails.logger.info "special_agent: #{req.path}"
    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.

Rack::Attack.blacklisted_response = lambda do |env|
  [ 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

  [ 503, {}, [body]]
end

For responses that did not exceed a throttle limit, Rack::Attack annotates the env with match data:

request.env['rack.attack.throttle_data'][name] # => { :count => n, :period => p, :limit => l }

Logging & Instrumentation

Rack::Attack uses the ActiveSupport::Notifications API if available.

You can subscribe to 'rack.attack' events and log it, graph it, etc:

ActiveSupport::Notifications.subscribe('rack.attack') do |name, start, finish, request_id, req|
  puts req.inspect
end

Performance

The overhead of running Rack::Attack is typically negligible (a few milliseconds per request), 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. A single typical ruby web server thread can block several hundred requests per second.

Rack::Attack complements tools like iptables and nginx's limit_zone module.

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.

See also: the Backing & Hacking blog post introducing Rack::Attack.

License

Released under an MIT License