django-brake 1.2.3

Examples

@ratelimit()
def myview(request):
    # Will be true if the same IP makes more than 5 requests/minute.
    was_limited = getattr(request, 'limited', False)
    return HttpResponse()

@ratelimit(block=True)
def myview(request):
    # If the same IP makes >5 reqs/min, will return HttpResponseForbidden
    return HttpResponse()

@ratelimit(field='username')
def login(request):
    # If the same username OR IP is used >5 times/min, this will be True.
    # The `username` value will come from GET or POST, determined by the
    # request method.
    was_limited = getattr(request, 'limited', False)
    return HttpResponse()

@ratelimit(method='POST')
def login(request):
    # Only apply rate-limiting to POSTs.
    return HttpResponseRedirect()

@ratelimit(field=['username', 'other_field'])
def login(request):
    # Use multiple field values.
    return HttpResponse()

@ratelimit(rate='1/m')
@ratelimit(rate='10/h')
@ratelimit(rate='100/d')
def slow(request):
    # Allow 1 reqs/min, 10 per hour, and 100 per day.
    return HttpResponse()

#
## Example Login Code to *only* block login failures
##

@ratelimit(field='username', method='POST', rate='5/m')
@ratelimit(field='username', method='POST', rate='10/h')
@ratelimit(field='username', method='POST', rate='20/d')
def ratelimit_login(request):
    """Increment cache counters, 403 if over limit."""

    was_limited = getattr(request, 'limited', False)
    if was_limited:
        request.flash['error'] = 'You have been ratelimited'
        # Log the error, etc.

        return http.HttpResponseRedirect(urlresolvers.reverse(
            'auth_login'
        ))



def login(request):
    """Just a regular django login flow."""
    form = forms.AuthenticationForm()
    if form.method == 'POST':
        form = forms.AuthenticationForm(data=request.POST):
            if form.is_valid()
                # Log in user and redirect to next page.

            # Login information was not correct.
            ratelimit_login(request)

# If you're interested in which endpoints failed, and what the
# counts were:

@ratelimit(field='username', method='POST', rate='1/m')
def login(request):
    # Limits is a dict that looks like this:
    # {'period': 60, 'field': 'username', 'count', 1}
    # This can give you more insight into how to deal with
    # the ratelimiting issue.
    limits =  getattr(request, 'limits', {})

    if limits:
        return http.HttpResponseRedirect(urlresolvers.reverse(
            'auth_login'
        ))

Some Required Customization

By default we only track the IP that we get form request.META[‘HOST_ADDR’]. Unless your webservers are sitting directly on routable IPs and have no loadbalancers or upstream proxies, this is probably not what you want!

Since this is a deployment detail, we leave this up to those who choose to implement Django Brake. You do so with a simple bit of Inheritence and override.

# In its own module, or in your view module; however you like:

from brake.backends import cachebe

class MyBrake(cachebe.CacheBackend):
    def get_ip(self, request):
        return request.META.get(
            'HTTP_TRUE_CLIENT_IP',
            request.META.get('REMOTE_ADDR')
    )

# Now in your settings.py:

RATELIMIT_CACHE_BACKEND = 'path.to.module.MyBrake'

Internals

These are variables which you do not need to modify directly, but are essential to the functioning of Brake

function_name:

This is the name of the function decorated with Brake; this allows us to separate into different “buckets” for each view. This is automatically added and doesn’t need to be specified.

period:

This is derrived from the rate information passed in as a string. It’s the number of seconds for which the increment on a bucket + period will be valid. It sets the TTL in memcache.

The cache key structure from one bad login attempt from our example above would look something like this:

# The form value derived counters:
rl:func:<function_name>:period:<60>:field:<username>:<sha1 of username>
rl:func:<function_name>:period:<3600>:field:<username>:<sha1 of username>
rl:func:<function_name>:period:<86400>:field:<username>:<sha1 of username>
# The IP derived counters:
rl:func:<function_name>:period:<60>:ip:<ip_address>
rl:func:<function_name>:period:<3600>:ip:<ip_address>
rl:func:<function_name>:period:<86500>:ip:<ip_address>

All period numbers are equivilent to the TTL for that key.

If any of these thresholds are passed, then the view will 403. This is a huge improvement in terms of usablity and security of many existing ratelimiting applications.