A Django app that implements IP-based blocklisting.
Project description
Django-blocklist
A Django app that implements IP-based blocklisting. It consists of a data model for the blocklist entries, and middleware that performs the blocking. It is mostly controlled by its management commands.
This app is primarily intended for use in 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
-
Add "blocklist" to your INSTALLED_APPS setting like this::
INSTALLED_APPS = [ ... "blocklist" ]
-
Add the middleware like this::
MIDDLEWARE = [ ... "blocklist.middleware.BlocklistMiddleware" ]
-
Customize settings (optional)::
BLOCKLIST_CONFIG = { "cooldown": 1, # Days to expire, default 7 "cache-ttl": 120, # Seconds that utils functions cache the full list, default 60 "denial-template": "Your IP address {ip} has been blocked for violating our Terms of Service. IP will be unblocked after {cooldown} days." }
-
Run
python manage.py migrate
to create theblocklist_blockedip
table. -
Add IPs to the list (via management commands,
utils.add_to_blocklist
, or the admin).
Management commands
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 successfulupdate_blocklist
— change thereason
orcooldown
values for existing entriesimport_blocklist
— convenience command for importing IPs from a filereport_blocklist
— information on the current entriesclean_blocklist
— remove entries that have fulfilled their cooldown period
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.
Reporting
The report_blocklist
command gives information about the current collection of IPs, including:
- Number of listed IPs
- Total number of blocked requests from listed IPs
- Number of IPs active in last 24 hours
- Number of stale IPs (added over 24h ago and not seen since)
- Five IPs with highest block count
- Five IPs most recently blocked
- Longest running entry
- IP counts by reason
Utility methods
The utils
module defines two convenience functions for updating the list from your application code:
add_to_blocklist(ips: set, reason="")
adds IPs to the blocklistremove_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
Hashes for django_blocklist-1.0.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1476122d5a74289e1650b17c69e2f350f31a050172a21d817468d9adc879b627 |
|
MD5 | 35d2b784fb6bec905a2d16cd5a833c2b |
|
BLAKE2b-256 | 13f0610668b7426b5028492d173b6d9fb5c84f79e5090a1ad98dbbb1426dad7a |