django-defender

A simple Django reusable app that blocks people from brute forcing login attempts. The goal is to make this as fast as possible, so that we do not slow down the login attempts.

We will use a cache so that it doesn't have to hit the database in order to check the database on each login attempt. The first version will be based on Redis, but the goal is to make this configurable so that people can use whatever backend best fits their needs.

Build status

Sites using Defender:

https://hub.docker.com

Versions

0.4.2 - Better support for Django 1.9
0.4.1 - minor refactor to make it easier to retrieve username.
0.4.0 - added DEFENDER_DISABLE_IP_LOCKOUT and added support for Python 3.5
0.3.2 - added DEFENDER_LOCK_OUT_BY_IP_AND_USERNAME, and changed settings to support django 1.8.
0.3.1 - fixed the management command name
0.3
- Added management command cleanup_django_defender to clean up access attempt table.
- Added DEFENDER_STORE_ACCESS_ATTEMPTS config to say if you want to store attempts to DB or not.
- Added DEFENDER_ACCESS_ATTEMPT_EXPIRATION config to specify how long to store the access attempt records in the db, before the management command cleans them up.
- changed the Django admin page to remove some filters which were making the page load slow with lots of login attempts in the database.
0.2.2 - bug fix add missing files to pypi package
0.2.1 - bug fix
0.2 - security fix for XFF headers
0.1.1 - setup.py fix
0.1 - initial release

Features

Log all login attempts to the database
support for reverse proxies with different headers for IP addresses
rate limit based on:
- username
- ip address
use redis for the blacklist
configuration
- redis server
  - host
  - port
  - database
  - password
  - key_prefix
- block length
- number of incorrect attempts before block
95% code coverage
full documentation
Ability to store login attempts to the database
Management command to clean up login attempts database table
admin pages
- list of blocked usernames and ip's
- ability to unblock people
- list of recent login attempts

Long term goals

pluggable backends, so people can use something other then redis.
email users when their account is blocked
add a whitelist for username and ip's that we will never block (admin's, etc)
add a permanent black list
- ip address
scan for known proxy ip's and don't block requests coming from those (improve the chances that a good IP is blocked)
add management command to prune old (configurable) login attempts.

Performance:

The goal of defender is to make it as fast as possible so that it doesn't slow down the login process. In order to make sure our goals are met we need a way to test the application to make sure we are on the right track. The best way to do this is to compare how fast a normal Django login takes with defender and django-axes.

The normal django login, would be our baseline, and we expect it to be the fastest of the 3 methods, because there are no additional checks happening.

The defender login would most likely be slower then the django login, and hopefully faster then the django-axes login. The goal is to make it as little of a difference between the regular raw login, and defender.

The django-axes login speed, will probably be the slowest of the three since it does more checks and does a lot of database queries.

The best way to determine the speed of a login is to do a load test against an application with each setup, and compare the login times for each type.

Types of Load tests

In order to make sure we cover all the different types of logins, in our load test we need to have more then one test.

All success:

We will do a load test with nothing but successful logins

Mixed: some success some failure:

We will load test with some successful logins and some failures to see how the failure effect the performance.

All Failures:

We will load test with all failure logins and see the difference in performance.

We will need a sample application that we can use for the load test, with the only difference is the configuration where we either load defender, axes, or none of them.

We can use a hosted load testing service, or something like jmeter. Either way we need to be consistent for all of the tests. If we use jmeter, we should have our jmeter configuration for others to run the tests on their own.

Results

We will post the results here. We will explain each test, and show the results along with some charts.

Why not django-axes

django-axes is great but it puts everything in the database, and this causes a bottle neck when you have a lot of data. It slows down the auth requests by as much as 200-300ms. This might not be much for some sites, but for others it is too long.

This started out as a fork of django-axes, and is using as much of their code as possible, and removing the parts not needed, and speeding up the lookups to improve the login.

requirements

django: 1.6.x, 1.7.x, 1.8.x, 1.9.x
redis
python: 2.6.x, 2.7.x, 3.3.x, 3.4.x, PyPy

How it works

When someone tries to login, we first check to see if they are currently blocked. We check the username they are trying to use, as well as the IP address. If they are blocked, goto step 5. If not blocked go to step 2.
They are not blocked, so we check to see if the login was valid. If valid go to step 6. If not valid go to step 3.
Login attempt wasn't valid. Add their username and IP address for this attempt to the cache. If this brings them over the limit, add them to the blocked list, and then goto step 5. If not over the limit goto step 4.
login was invalid, but not over the limit. Send them back to the login screen to try again.
User is blocked: Send them to the blocked page, telling them they are blocked, and give an estimate on when they will be unblocked.
Login is valid. Reset any failed login attempts, and forward to their destination.

Cache backend:

cache keys:

Counters:

prefix:failed:ip:[ip] (count, TTL)
prefix:failed:username:[username] (count, TTL)

Booleans (if present it is blocked):

prefix:blocked:ip:[ip] (true, TTL)
prefix:blocked:username:[username] (true, TTL)

Installing Django-defender

Download code, and run setup.

    $ pip install django-defender

    or

    $ python setup.py install

    or

    $ pip install -e git+http://github.com/kencochrane/django-defender.git#egg=django_defender-dev

First of all, you must add this project to your list of INSTALLED_APPS in settings.py::

INSTALLED_APPS = (
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.sites',
    ...
    'defender',
    ...
    )

Next, install the FailedLoginMiddleware middleware::

    MIDDLEWARE_CLASSES = (
        'django.middleware.common.CommonMiddleware',
        'django.contrib.sessions.middleware.SessionMiddleware',
        'django.contrib.auth.middleware.AuthenticationMiddleware',
        'defender.middleware.FailedLoginMiddleware'
        )

If you want to manage the blocked users via the Django admin, then add the following to your urls.py

urlpatterns = patterns(
    '',
    (r'^admin/', include(admin.site.urls)), # normal admin
    (r'^admin/defender/', include('defender.urls')), # defender admin
    # your own patterns follow…
)

Management Commands:

cleanup_django_defender:

If you have a website with a lot of traffic, the AccessAttempts table will get full pretty quickly. If you don't need to keep the data for auditing purposes there is a management command to help you keep it clean.

It will look at your DEFENDER_ACCESS_ATTEMPT_EXPIRATION setting to determine which records will be deleted. Default if not specified, is 24 hours.

$ python manage.py cleanup_django_defender

You can set this up as a daily or weekly cron job to keep the table size down.

# run at 12:24 AM every morning.
24 0 * * * /usr/bin/python manage.py cleanup_django_defender >> /var/log/django_defender_cleanup.log

Admin Pages:

Database tables:

You will need to create tables in your database that are necessary for operation.

If you're using Django 1.7.x:

python manage.py migrate defender

On versions of Django prior to 1.7, you might use South (version >= 1.0).

python manage.py migrate defender

If you're not using South, a normal syncdb will work:

python manage.py syncdb

Customizing Defender

You have a couple options available to you to customize django-defender a bit. These should be defined in your settings.py file.

DEFENDER_LOGIN_FAILURE_LIMIT: Int: The number of login attempts allowed before a record is created for the failed logins. [Default: 3]
DEFENDER_BEHIND_REVERSE_PROXY: Boolean: Is defender behind a reverse proxy? [Default: False]
DEFENDER_LOCK_OUT_BY_IP_AND_USERNAME: Boolean: Locks a user out based on a combination of IP and Username. This stops a user denying access to the application for all other users accessing the app from behind the same IP address. [Default: False]
DEFENDER_DISABLE_IP_LOCKOUT: Boolean: If this is True, it will not lockout the users IP address, it will only lockout the username. [Default: False]
DEFENDER_DISABLE_USERNAME_LOCKOUT: Boolean: If this is True, it will not lockout usernames, it will only lockout IP addresess. [Default: False]
DEFENDER_COOLOFF_TIME: Int: If set, defines a period of inactivity after which old failed login attempts will be forgotten. An integer, will be interpreted as a number of seconds. If 0, the locks will not expire. [Default: 300]
DEFENDER_LOCKOUT_TEMPLATE: String: [Default: None] If set, specifies a template to render when a user is locked out. Template receives the following context variables:
- cooloff_time_seconds: The cool off time in seconds
- cooloff_time_minutes: The cool off time in minutes
- failure_limit: The number of failures before you get blocked.
DEFENDER_USERNAME_FORM_FIELD: String: the name of the form field that contains your users usernames. [Default: username]
DEFENDER_REVERSE_PROXY_HEADER: String: the name of the http header with your reverse proxy IP address [Default: HTTP_X_FORWARDED_FOR]
DEFENDER_CACHE_PREFIX: String: The cache prefix for your defender keys. [Default: defender]
DEFENDER_LOCKOUT_URL: String: The URL you want to redirect to if someone is locked out.
DEFENDER_REDIS_URL: String: the redis url for defender. [Default: redis://localhost:6379/0] (Example with password: redis://:mypassword@localhost:6379/0)
DEFENDER_STORE_ACCESS_ATTEMPTS: Boolean: If you want to store the login attempt to the database, set to True. If False, it is not saved [Default: True]
DEFENDER_USE_CELERY: Boolean: If you want to use Celery to store the login attempt to the database, set to True. If False, it is saved inline. [Default: False]
DEFENDER_ACCESS_ATTEMPT_EXPIRATION: Int: Length of time in hours for how long to keep the access attempt records in the database before the management command cleans them up. [Default: 24]

Running Tests

Tests can be run, after you clone the repository and having Django installed, like:

$ PYTHONPATH=$PYTHONPATH:$PWD django-admin.py test defender --settings=defender.test_settings

With Code coverage:

PYTHONPATH=$PYTHONPATH:$PWD coverage run --source=defender $(which django-admin.py) test defender --settings=defender.test_settings

pombredanne / django-defender Goto Github PK

django-defender's Introduction