django-waf

Self-hosted request filtering, bot management, and WAF middleware for Django.

Provides two-layer defence (nginx + Django middleware) with rate limiting, user-agent anomaly scoring, JS proof-of-work challenges, path-based threat scoring, nginx blocklist generation, and collective threat feed integration, all configurable without a reverse-proxy vendor.

Features

• Rate limiting: sliding-window per-IP limits (burst, per-minute, per-5-min)
• UA anomaly scoring: heuristic detection of impossible OS/browser combos, ancient versions, scraper libraries
• Path-based threat scoring: suspicious path detection for credential probes (.env, wp-config, AWS/SSH config files) adds to the anomaly score
• HTTP method filtering: block non-standard methods (e.g. HEAD, OPTIONS, PUT, PATCH, DELETE) before rule evaluation
• JS proof-of-work challenges: hashcash-style SHA-256 challenges for suspicious clients (no CAPTCHAs, no third-party dependencies)
• Challenge auto-escalation: repeat offenders who exceed the unsolved-challenge threshold are automatically blocked for a configurable TTL
• No-referer challenge trigger: optionally challenge direct-navigation requests lacking a Referer header
• GeoIP country code population: attach ISO country codes to request log entries using a MaxMind GeoLite2 database
• Composite rules: block rules combining UA pattern with IP/CIDR
• In-process rule cache: version-checked in-memory cache avoids Redis round trips on every request; invalidated automatically when rules change
• Hit count tracking: block rules accumulate hit counts, flushed to the database periodically
• Configurable anomaly score thresholds: separate thresholds for log, challenge, and block verdicts
• nginx blocklist generation: exports map/geo blocks for C-level filtering at < 0.01 ms latency
• Anomaly detection: auto-creates expiring rules for UA rotation, subnet bursts, and challenge farms
• Collective threat feed: opt-in sync of anonymised threat intelligence across deployments
• Staff dashboard: HTMX-powered real-time analytics with anomaly management
• Form protection: defence-in-depth at the form layer: signed render tokens, honeypots, time-trap, UA-consistency, JS-touch, credential throttle (enumeration-safe), signup velocity, per-submission PoW. Mixin / decorator / template-tag entry points; per-form configuration; optional challenge-replay for false-positive rescue
• Fail-open design: Redis outage never breaks the site

Requirements

• Python >= 3.11
• Django >= 5.2
• Redis (via django-redis >= 5.4)
• httpx >= 0.27 (for threat feed sync)
• Optional: celery >= 5.3 (for scheduled tasks)
• Optional: maxminddb >= 2.4 (for GeoIP lookups)

Installation

pip install django-waf

With optional extras:

pip install django-waf[geoip]    # adds maxminddb for GeoIP support
pip install django-waf[celery]   # adds celery for scheduled tasks

Add to INSTALLED_APPS:

INSTALLED_APPS = [
    # ...
    "django_waf",
]

Add the middleware, placing it after SecurityMiddleware and before other middleware so it can block requests early:

MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "django_waf.middleware.WafMiddleware",        # <-- here
    "django.contrib.sessions.middleware.SessionMiddleware",
    "django.middleware.common.CommonMiddleware",
    # ...
]

Include the URL routes for the challenge flow and staff dashboard:

# urls.py
from django.urls import include, path

urlpatterns = [
    path("waf/", include("django_waf.urls")),
    # ...
]

Configure a Redis cache backend (required for rate limiting):

CACHES = {
    "default": {
        "BACKEND": "django_redis.cache.RedisCache",
        "LOCATION": "redis://127.0.0.1:6379/0",
        "OPTIONS": {
            "CLIENT_CLASS": "django_redis.client.DefaultClient",
        },
    }
}

Run migrations:

python manage.py migrate django_waf

Settings Reference

All settings are namespaced under DJANGO_WAF_* and have sensible defaults.

Core

Rate Limiting

Challenges

Anomaly Scoring

Logging

GeoIP

nginx Integration

Collective Threat Feed

Form protection (v0.11.0)

The form-protection subsystem is opt-in per form. Defaults are inert until a form opts in via the mixin, decorator, or template tag.

Usage: Django Form mixin (recommended for new forms):

from django import forms
from django_waf.forms import FormProtection, ProtectedForm

class ContactForm(ProtectedForm, forms.Form):
    name = forms.CharField()
    email = forms.EmailField()
    message = forms.CharField(widget=forms.Textarea)

    waf = FormProtection(
        form_id="contact",
        defences=("render_token", "honeypot", "time_trap", "ua_consistency"),
    )

In the view:

def contact_view(request):
    form = ContactForm(request.POST or None, request=request)
    if request.method == "POST" and form.is_valid():
        # form.waf_result holds the FormEvaluationResult.
        ...

In the template:

<form method="post">
  {% csrf_token %}
  {{ form.waf_fields }}
  {{ form.as_p }}
  <button type="submit">Send</button>
</form>

Handwritten HTML (forms that bypass Django's Form layer):

# views.py
from django_waf.forms import waf_protect_post

@waf_protect_post(form_id="contact-handwritten",
                  defences=("honeypot", "time_trap"))
def contact_view(request):
    if request.method == "POST":
        ...

<!-- contact.html -->
{% load waf_form_tags %}
<form method="post">
  {% csrf_token %}
  {% waf_protect form_id="contact-handwritten" %}
  <input type="email" name="email">
  <button type="submit">Send</button>
</form>

HTMX compatibility: the form-protection render token persists across HTMX re-renders of the same form (a user fixing a validation error keeps the same token). The Redis marker that backs replay protection is consumed only on a PASS verdict, so submitting twice in succession after a validation error works correctly. Operators must ensure the HTMX target includes {{ form.waf_fields }} / {% waf_protect %} in the swapped fragment.

Authenticated forms: set skip_for_authenticated=True on FormProtection to drop the spam-style defences for logged-in users while keeping render_token for integrity:

waf = FormProtection(
    form_id="team-invite",
    defences=("render_token",),
    skip_for_authenticated=True,
)

Celery Beat Schedule

If using Celery, configure the beat schedule for automated tasks:

from celery.schedules import crontab

CELERY_BEAT_SCHEDULE = {
    "django-waf-flush-rule-hit-counts": {
        "task": "django_waf.tasks.flush_rule_hit_counts",
        "schedule": crontab(minute="*/5"),
    },
    "django-waf-generate-blocklist": {
        "task": "django_waf.tasks.generate_blocklist",
        "schedule": crontab(minute="*/5"),
    },
    "django-waf-detect-anomalies": {
        "task": "django_waf.tasks.detect_anomalies",
        "schedule": crontab(minute="*/15"),
    },
    "django-waf-parse-access-log": {
        "task": "django_waf.tasks.parse_access_log",
        "schedule": crontab(minute="*/10"),
    },
    "django-waf-expire-rules": {
        "task": "django_waf.tasks.expire_rules",
        "schedule": crontab(minute="*/30"),
    },
    "django-waf-update-ip-reputation": {
        "task": "django_waf.tasks.update_ip_reputation",
        "schedule": crontab(hour="*/6", minute=0),
    },
    "django-waf-prune-request-logs": {
        "task": "django_waf.tasks.prune_request_logs",
        "schedule": crontab(hour=4, minute=0),
    },
    "django-waf-sync-threat-feed": {
        "task": "django_waf.tasks.sync_threat_feed",
        "schedule": crontab(hour=4, minute=30),
    },
    "django-waf-report-threat-telemetry": {
        "task": "django_waf.tasks.report_threat_telemetry",
        "schedule": crontab(hour=5, minute=0),
    },
}

Management Commands

Dashboard

The staff dashboard is available at /waf/dashboard/ for authenticated staff users. It provides:

• Real-time traffic counters (allowed, blocked, challenged, throttled)
• Top 10 blocked IPs
• Auto-detected anomalies awaiting review

Superusers can confirm auto-generated rules (promoting them to permanent) or reject them (deactivating) directly from the anomalies panel.

Architecture

Client → nginx (C-level blocklist, < 0.01 ms)
       → Django WafMiddleware (dynamic analysis, < 0.5 ms)
       → Application views

The middleware evaluates requests in this order:

1. Exempt paths/hosts bypass: static assets, health endpoints, and exempt hosts skip all evaluation
2. HTTP method filtering: disallowed methods receive 405 immediately
3. Master switch check: DJANGO_WAF_ENABLED = False passes all requests through
4. Staff/superuser bypass: authenticated staff skip rule evaluation
5. Valid challenge cookie check: previously-solved challenges are honoured
6. Allow rules → Block rules → Rate limits: explicit rule matching
7. No-referer challenge: optionally challenge requests with no Referer header
8. Path scoring (always) + UA scoring (after 10 requests): anomaly score accumulates from suspicious paths and UA heuristics; score thresholds determine the verdict (log / challenge / block)
9. Challenge escalation: IPs exceeding the unsolved-challenge threshold are auto-blocked for DJANGO_WAF_ESCALATION_BLOCK_TTL seconds
10. Verdict dispatch: response rendered (allow / block / challenge / throttle), sampled logging written, and WAF signal emitted

Development

# Run tests
pytest

# Run tests with coverage
pytest --cov=src --cov-report=term-missing

# Lint
ruff check src/ tests/
ruff format src/ tests/

# Type check
mypy src/

Licence

MIT