Rack::Attack

A DSL for blocking & thottling abusive clients

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.

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

Installation

Add rack-attack 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. By default, there are no whitelists, blacklists, or throttles.

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

# 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

# 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

# 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

Note that req is a Rack::Request object.

Logging & Instrumentation

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.

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)

3.5 KiB Raw Blame History