A Django app that implements IP-based blocklisting.
Project description
Django-blocklist
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.
Quick start
-
The PyPI package name is
django-blocklist
; add that to yourrequirements.txt
or otherwise install it into your project's Python environment. -
Add "django_blocklist" to settings.INSTALLED_APPS
-
Add "django_blocklist.middleware.BlocklistMiddleware" to settings.MIDDLEWARE
-
Run
python manage.py migrate
to create thedjango_blocklist_blockedip
table. -
Add IPs to the list (via management commands,
utils.update_blocklist
, or the admin). -
Set up a cron job or equivalent to run
manage.py clean_blocklist
daily.
Management commands
Django-blocklist includes several management commands:
clean_blocklist
— remove entries that have fulfilled their cooldown periodimport_blocklist
— convenience command for importing IPs from a fileremove_from_blocklist
— remove one or more IPsreport_blocklist
— information on the current entriessearch_blocklist
— look for an IP in the list; in addition to info on stdout, returns an exit code of 0 if successfulupdate_blocklist
— add/update IPs;--reason
and--cooldown
optional; use--skip-existing
to avoid updating existing records
The --help
for each of these details its available options.
For exporting or importing BlockedIP entries, use Django's built-in dumpdata
and loaddata
management commands.
Configuration
You can customize the following settings via a BLOCKLIST_CONFIG
dict in your project settings:
cooldown
— Days to expire, for new entries; default 7cache-ttl
— Seconds to cache the list of blocked IPs; default 60denial-template
— For the denial response; an f-string with{ip}
and{cooldown}
placeholders
Reporting
The report_blocklist
command gives summary information about the current collection of IPs, including how many requests from those IPs have been blocked. See the sample report for more.
Utility methods
The utils
module defines two convenience functions for updating the list from your application code:
update_blocklist(ips: set, reason: str, cooldown: int, last_seen: datetime)
adds IPs to the blocklist (all args exceptset
are optional)remove_from_blocklist(ip: str)
removes an entry, returningTrue
if successful
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file django_blocklist-2.8.1.tar.gz
.
File metadata
- Download URL: django_blocklist-2.8.1.tar.gz
- Upload date:
- Size: 15.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.8.3 CPython/3.12.7 Darwin/24.0.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 755c024d42fe75265a32c1667228ebe5e6ff601f8c8db5bc7f2de4b5d02ca022 |
|
MD5 | ed5512acbac17cf9dfe493f08e697361 |
|
BLAKE2b-256 | 2c0da03f3b81167e3a5ad827a70a329f5d9f667ebc999f858ac8039c35df1bdd |
File details
Details for the file django_blocklist-2.8.1-py3-none-any.whl
.
File metadata
- Download URL: django_blocklist-2.8.1-py3-none-any.whl
- Upload date:
- Size: 22.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.8.3 CPython/3.12.7 Darwin/24.0.0
File hashes
Algorithm | Hash digest | |
---|---|---|
SHA256 | 334aade2c180f005086bdb49af779e439e767d913c6dcd286b558e744aa4e6a2 |
|
MD5 | c18a3d362b848042c44c088721a543da |
|
BLAKE2b-256 | 64c93857b36e0b44c19787d056514c9ba59c73d4c59a5496165b79bcf28ec7f3 |