This is a Django app that implements IP-based blocklisting. Its
BlocklistMiddleware performs the blocking, and its
clean_blocklist management command deletes entries which have satisfied the cooldown period. Entries also have a
reason field, used in reporting. There are utility functions to add/remove IPs, an admin, and several management commands.
This app is primarily for situations where server-level blocking is not available, e.g. on platform-as-a-service hosts like PythonAnywhere or Heroku. Being an application-layer solution, it's not as performant as blocking via firewall or web server process, but is suitable for moderate traffic sites. It also offers better integration with the application stack, for easier management.
The PyPI package name is
django-blocklist; add that to your
requirements.txt or otherwise install it into your project's Python environment.
Add "django_blocklist" to your INSTALLED_APPS setting like this:
INSTALLED_APPS = [ ... "django_blocklist" ]
Add the middleware like this:
MIDDLEWARE = [ ... "django_blocklist.middleware.BlocklistMiddleware" ]
python manage.py migrate to create the
Add IPs to the list (via management commands,
utils.add_to_blocklist, or the admin).
Set up a
cron job or equivalent to run
manage.py clean_blocklist daily.
Django-blocklist includes several management commands:
add_to_blocklist— (one or more IPs)
remove_from_blocklist— (one or more IPs)
search_blocklist— look for an IP in the list; in addition to info on stdout, returns an exit code of 0 if successful
update_blocklist— change the
cooldownvalues for existing entries
import_blocklist— convenience command for importing IPs from a file
report_blocklist— information on the current entries
clean_blocklist— remove entries that have fulfilled their cooldown period
--help for each of these details its available options.
For exporting or importing BlockedIP entries, use Django's built-in
loaddata management commands.
You can customize the following settings via a
BLOCKLIST_CONFIG dict in your project settings:
cooldown— Days to expire, for new entries; default 7
cache-ttl— Seconds that utils functions cache the full list; default 60
denial-template— For the denial response; an f-string with
report_blocklist command gives information about the current collection of IPs, including:
utils module defines two convenience functions for updating the list from your application code:
add_to_blocklist(ips: set, reason="")adds IPs to the blocklist
remove_from_blocklist(ip: str)removes an entry, returning