django-axesKeep track of failed login attempts in Django-powered sites.Django Axes
===========
.. image:: https://secure.travis-ci.org/django-security/django-axes.png?branch=master
:alt: Build Status
:target: http://travis-ci.org/django-security/django-axes
``django-axes`` is a very simple way for you to keep track of failed login
attempts, both for the Django admin and for the rest of your site. The name is
sort of a geeky pun, since ``axes`` can be read interpreted as:
* "access", as in monitoring access attempts
* "axes", as in tools you can use hack (generally on wood). In this case,
however, the "hacking" part of it can be taken a bit further: ``django-axes``
is intended to help you *stop* people from hacking (popular media
definition) your website. Hilarious, right? That's what I thought too!
Requirements
============
``django-axes`` requires Django 1.4 or later. The application is intended to
work around the Django admin and the regular ``django.contrib.auth``
login-powered pages.
Installation
============
Download and install ``django-axes`` using **one** of the following methods:
PIP
---
You can install the latest stable package running this command::
$ pip install django-axes
Also you can install the development version running this command::
$ pip install -e git+http://github.com/django-security/django-axes.git#egg=django_axes-dev
Setuptools
----------
You can install the latest stable package running::
$ easy_install django-axes
Development
===========
You can contribute to this project forking it from github and sending pull requests.
Running tests
-------------
Tests can be run, after you clone the repository and having django installed, like::
$ PYTHONPATH=$PYTHONPATH:$PWD django-admin.py test axes --settings=axes.test_settings
Configuration
=============
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',
...
'axes',
...
)
Next, install the ``FailedLoginMiddleware`` middleware::
MIDDLEWARE_CLASSES = (
'django.middleware.common.CommonMiddleware',
'django.contrib.sessions.middleware.SessionMiddleware',
'django.contrib.auth.middleware.AuthenticationMiddleware',
'axes.middleware.FailedLoginMiddleware'
)
Run ``python manage.py syncdb``. This creates the appropriate tables in your database
that are necessary for operation.
Customizing Axes
----------------
You have a couple options available to you to customize ``django-axes`` a bit.
These should be defined in your ``settings.py`` file.
* ``AXES_LOGIN_FAILURE_LIMIT``: The number of login attempts allowed before a
record is created for the failed logins. Default: ``3``
* ``AXES_LOCK_OUT_AT_FAILURE``: After the number of allowed login attempts
are exceeded, should we lock out this IP (and optional user agent)?
Default: ``True``
* ``AXES_USE_USER_AGENT``: If ``True``, lock out / log based on an IP address
AND a user agent. This means requests from different user agents but from
the same IP are treated differently. Default: ``False``
* ``AXES_COOLOFF_TIME``: If set, defines a period of inactivity after which
old failed login attempts will be forgotten. Can be set to a python
timedelta object or an integer. If an integer, will be interpreted as a
number of hours. Default: ``None``
* ``AXES_LOGGER``: If set, specifies a logging mechanism for axes to use.
Default: ``'axes.watch_login'``
* ``AXES_LOCKOUT_TEMPLATE``: If set, specifies a template to render when a
user is locked out. Template receives cooloff_time and failure_limit as
context variables. Default: ``None``
* ``AXES_LOCKOUT_URL``: If set, specifies a URL to redirect to on lockout. If
both AXES_LOCKOUT_TEMPLATE and AXES_LOCKOUT_URL are set, the template will
be used. Default: ``None``
* ``AXES_VERBOSE``: If ``True``, you'll see slightly more logging for Axes.
Default: ``True``
Usage
=====
Using ``django-axes`` is extremely simple. Once you install the application
and the middleware, all you need to do is periodically check the Access
Attempts section of the admin.
By default, django-axes will lock out repeated attempts from the same IP
address. You can allow this IP to attempt again by deleting the relevant
``AccessAttempt`` records in the admin.
You can also use the ``axes_reset`` management command using Django's
``manage.py``.
* ``manage.py axes_reset`` will reset all lockouts and access records.
* ``manage.py axes_reset ip`` will clear lockout/records for ip
In your code, you can use ``from axes.utils import reset``.
* ``reset()`` will reset all lockouts and access records.
* ``reset(ip=ip)`` will clear lockout/records for ip
* ``reset(username=username)`` will clear lockout/records for username
Changes
=======
1.3.6 (2013-11-23)
------------------
- Added AttributeError in case get_profile doesn't exist [camilonova]
- Improved axes_reset command [camilonova]
1.3.5 (2013-11-01)
------------------
- Fix an issue with __version__ loading the wrong version [graingert]
1.3.4 (2013-11-01)
------------------
- Update README.rst for PyPI [marty] [camilonova] [graingert]
- Add cooloff period [visualspace]
1.3.3 (2013-07-05)
------------------
- Added 'username' field to the Admin table [bkvirendra]
- Removed fallback logging creation since logging cames by default on django 1.4 or later, if you don't have it is because you explicitly wanted. Fixes #45 [camilonova]
1.3.2 (2013-03-28)
------------------
- Fix an issue when a user logout [camilonova]
- Match pypi version [camilonova]
- Better User model import method [camilonova]
- Use only one place to get the version number [camilonova]
- Fixed an issue when a user on django 1.4 logout [camilonova]
- Handle exception if there is not user profile model set [camilonova]
- Made some cleanup and remove a pokemon exception handling [camilonova]
- Improved tests so it really looks for the rabbit in the hole [camilonova]
- Match pypi version [camilonova]
1.3.1 (2013-03-19)
------------------
- Add support for Django 1.5 [camilonova]
1.3.0 (2013-02-27)
------------------
- Bug fix: get_version() format string [csghormley]
1.2.9 (2013-02-20)
------------------
- Add to and improve test cases [camilonova]
1.2.8 (2013-01-23)
------------------
- Increased http accept header length [jslatts]
1.2.7 (2013-01-17)
------------------
- Reverse proxy support [rmagee]
- Clean up README [martey]
1.2.6 (2012-12-04)
------------------
- Remove unused import [aclark]
1.2.5 (2012-11-28)
------------------
- Fix setup.py [aclark]
- Added ability to flag user accounts as unlockable. [kencochrane]
- Added ipaddress as a param to the user_locked_out signal. [kencochrane]
- Added a signal receiver for user_logged_out. [kencochrane]
- Added a signal for when a user gets locked out. [kencochrane]
- Added AccessLog model to log all access attempts. [kencochrane]Alex Clark2dce877ecbcde995cf3f551e3163da407553ce931.3.6