Skip to main content

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

  1. The PyPI package name is django-blocklist; add that to your requirements.txt or otherwise install it into your project's Python environment.

  2. Add "django_blocklist" to settings.INSTALLED_APPS

  3. Add "django_blocklist.middleware.BlocklistMiddleware" to settings.MIDDLEWARE

  4. Run python manage.py migrate to create the django_blocklist_blockedip table.

  5. Add IPs to the list (via management commands, utils.update_blocklist, or the admin).

  6. 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 period
  • import_blocklist — convenience command for importing IPs from a file
  • remove_from_blocklist — remove one or more IPs
  • report_blocklist — information on the current entries
  • 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 — 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 7
  • cache-ttl — Seconds to cache the list of blocked IPs; default 60
  • denial-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 except set are optional)
  • remove_from_blocklist(ip: str) removes an entry, returning True if successful

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

django_blocklist-2.8.1.tar.gz (15.1 kB view details)

Uploaded Source

Built Distribution

django_blocklist-2.8.1-py3-none-any.whl (22.9 kB view details)

Uploaded Python 3

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

Hashes for django_blocklist-2.8.1.tar.gz
Algorithm Hash digest
SHA256 755c024d42fe75265a32c1667228ebe5e6ff601f8c8db5bc7f2de4b5d02ca022
MD5 ed5512acbac17cf9dfe493f08e697361
BLAKE2b-256 2c0da03f3b81167e3a5ad827a70a329f5d9f667ebc999f858ac8039c35df1bdd

See more details on using hashes here.

File details

Details for the file django_blocklist-2.8.1-py3-none-any.whl.

File metadata

File hashes

Hashes for django_blocklist-2.8.1-py3-none-any.whl
Algorithm Hash digest
SHA256 334aade2c180f005086bdb49af779e439e767d913c6dcd286b558e744aa4e6a2
MD5 c18a3d362b848042c44c088721a543da
BLAKE2b-256 64c93857b36e0b44c19787d056514c9ba59c73d4c59a5496165b79bcf28ec7f3

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page