django-firewall 2.0.8

IP-based firewall protection for Django with path rule management.

Django Firewall

A reusable Django app for IP-based firewall protection with automatic blocking of suspicious requests.

Features

• Middleware-based protection: Automatically monitors and blocks suspicious requests
• Database-driven path rules: Manage blacklist/whitelist patterns via Django Admin without code changes
• IP/network whitelist: Protect trusted IP addresses and CIDR networks from automatic or manual blocking
• Pre-configured attack patterns: Includes common malicious URL patterns (PHP probes, .env files, Git exposure, WordPress attacks, etc.)
• Caching system: 5-minute cache for path rules with automatic invalidation
• Priority-based rules: Control the order in which rules are evaluated
• CloudFlare & proxy support: Correctly detects real client IPs behind proxies
• Admin interface: Manage blocked/allowed IPs and path rules through Django Admin
• REST API: Optional API endpoints (requires Django REST Framework)
• Management commands: CLI tools for blocking/unblocking IPs, viewing logs, and importing rules or whitelist entries
• Docker support: Auto-detect host IP in containerized environments
• Cloudflare WAF export: Generate Cloudflare-compatible WAF rules

Requirements

• Python 3.10+
• Django 4.2+
• requests 2.28+
• (Optional) Django REST Framework 3.14+ for API endpoints

Installation

Install from Git (pip)

This package can be installed directly from the repository as a subdirectory:

pip install django_firewall

With optional Django REST Framework support:

pip install django_firewall[rest]

Install from Git (Poetry)

poetry add django_firewall

With optional Django REST Framework support:

[tool.poetry.dependencies]
django_firewall = { extras = ["rest"] }

Manual install

Copy the django_firewall directory to your project.

Quick Start

1. Add to INSTALLED_APPS

INSTALLED_APPS = [
    # ...
    'django_firewall',
    # ...
]

2. Add middleware (optional but recommended)

MIDDLEWARE = [
    # Add early in the middleware stack for best protection
    'django_firewall.middleware.FirewallMiddleware',
    # ...
]

3. Run migrations

python manage.py migrate django_firewall

4. Configure settings

# Enable the firewall
DJANGO_FIREWALL_ENABLED = True

# URL of your external firewall service (optional)
DJANGO_FIREWALL_URL = "http://firewall-host:8080"

# Port for the firewall service
DJANGO_FIREWALL_PORT = 8080

# Request timeout in seconds
DJANGO_FIREWALL_REQUEST_TIMEOUT = 5

# Additional URL patterns to monitor (extends defaults)
DJANGO_FIREWALL_URLS_LIST = [
    "/my-sensitive-path/.*",
]

# URL patterns to whitelist (skip monitoring)
DJANGO_FIREWALL_URL_WHITE_LIST = [
    "/api/health/",
]

# IP addresses and CIDR networks that should never be blocked
DJANGO_FIREWALL_IP_WHITE_LIST = [
    "203.0.113.10",
    "10.0.0.0/8",
    "2001:db8::/32",
]

5. (Optional) Add API URLs

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

urlpatterns = [
    # ...
    path('api/firewall/', include('django_firewall.urls')),
]

Configuration Options

Setting	Default	Description
DJANGO_FIREWALL_ENABLED	False	Enable/disable the firewall
DJANGO_FIREWALL_URL	None	URL of external firewall service
DJANGO_FIREWALL_PORT	8080	Port for firewall service
DJANGO_FIREWALL_REQUEST_TIMEOUT	5	Timeout for firewall API calls (seconds)
DJANGO_FIREWALL_GET_HOST_SCRIPT	Auto	Script to detect host IP in Docker
DJANGO_FIREWALL_URLS_LIST	See below	URL patterns to monitor
DJANGO_FIREWALL_URL_WHITE_LIST	[]	URL patterns to skip
DJANGO_FIREWALL_IP_WHITE_LIST	[]	IP addresses or CIDR networks that should never be blocked

Backwards Compatibility

For backwards compatibility with the original Kapybar firewall, these settings are also supported:

• USE_FIREWALL (same as DJANGO_FIREWALL_ENABLED)
• FIREWALL_URL (same as DJANGO_FIREWALL_URL)
• FIREWALL_PORT (same as DJANGO_FIREWALL_PORT)
• FIREWALL_GET_HOST_SCRIPT (same as DJANGO_FIREWALL_GET_HOST_SCRIPT)
• FIREWALL_URLS_LIST (same as DJANGO_FIREWALL_URLS_LIST)
• FIREWALL_URL_WHITE_LIST (same as DJANGO_FIREWALL_URL_WHITE_LIST)
• FIREWALL_IP_WHITE_LIST (same as DJANGO_FIREWALL_IP_WHITE_LIST)

Default Blocked Patterns

The firewall comes pre-configured to block common attack patterns:

• PHP files and probes (*.php, /phpinfo.php)
• Environment files (/.env, /admin/.env.*)
• Configuration files (/config.json, /config/*)
• Git repository exposure (/.git/*)
• AWS credentials (/.aws/*, /.s3cfg)
• Firebase configuration (/firebase.*)
• WordPress attacks (/wp-admin/*, /wp-content/*)
• Apache/Nginx sensitive files (/.htaccess, /.htpasswd)
• Symfony profiler (/_profiler/*)

Database-Driven Path Rules (NEW)

The firewall now supports managing blacklist and whitelist path patterns through the Django admin interface.

Path rules quick start

# Import hardcoded rules into database
python manage.py import_firewall_rules

# Preview what would be imported (dry run)
python manage.py import_firewall_rules --dry-run

# Clear existing rules and import fresh
python manage.py import_firewall_rules --clear

Managing Rules via Admin

1. Navigate to Django Firewall → Firewall Path Rules in Django Admin
2. Create, edit, or delete rules without modifying code
3. Set priorities to control rule evaluation order
4. Enable/disable rules temporarily without deletion
5. Changes take effect automatically (cached for 5 minutes)

Path rules features

• Database storage: Rules stored in FirewallPathRule model
• Priority system: Lower priority numbers = higher priority
• Rule types: Blacklist (block) or Whitelist (allow)
• Performance: 5-minute caching with automatic invalidation
• Fallback: Falls back to hardcoded rules if database is empty
• Audit trail: Created/updated timestamps on all rules

Documentation

• Detailed Guide - Comprehensive documentation
• Quick Setup - 3-step setup guide
• Implementation - Technical details

IP/Network Whitelist

Trusted IP addresses and CIDR networks can be whitelisted so they are never blocked by the middleware, Django admin actions, management commands, or direct calls to block_ip.

Whitelist entries can come from:

• DJANGO_FIREWALL_IP_WHITE_LIST / FIREWALL_IP_WHITE_LIST settings or environment variables
• FirewallIPWhitelist records managed in Django Admin

Supported entries include exact IPv4/IPv6 addresses and CIDR networks:

DJANGO_FIREWALL_IP_WHITE_LIST = [
    "203.0.113.10",
    "10.0.0.0/8",
    "2001:db8::/32",
]

Environment variables use comma-separated values:

DJANGO_FIREWALL_IP_WHITE_LIST="203.0.113.10,10.0.0.0/8,2001:db8::/32"

Managing IP Whitelist via Admin

1. Navigate to Django Firewall -> Firewall IP Whitelist in Django Admin
2. Add an exact IP address or CIDR network
3. Use the enabled flag to temporarily disable an entry without deleting it
4. Changes take effect automatically through cache invalidation

Importing IP Whitelist Entries

Import one IP address or network:

python manage.py firewall --import-whitelist-ip 203.0.113.10 --description "Office IP"
python manage.py firewall --import-whitelist-ip 10.0.0.0/8 --description "Private network"

Import from a text file:

python manage.py firewall --import-whitelist-ip-file whitelist.txt --description "Trusted networks"

Text file format:

# one IP address or CIDR network per line
203.0.113.10
10.0.0.0/8 # inline comments are allowed
2001:db8::/32

Blank lines and comments are skipped. Invalid entries are reported in the command summary.

Management Commands

Firewall Management

# Show firewall status
python manage.py firewall --status

# List all blocked/allowed IPs
python manage.py firewall --list

# List monitored URL patterns
python manage.py firewall --list-paths

# Block an IP address
python manage.py firewall --block 1.2.3.4

# Unblock an IP address
python manage.py firewall --unblock 1.2.3.4

# Export logs to CSV
python manage.py firewall --csv firewall_logs.csv

# Import a trusted IP/network into the whitelist
python manage.py firewall --import-whitelist-ip 203.0.113.10 --description "Office IP"

# Import trusted IPs/networks from a text file
python manage.py firewall --import-whitelist-ip-file whitelist.txt --description "Trusted networks"

Path Rules Management

# Import hardcoded rules into database
python manage.py import_firewall_rules

# Preview import without making changes
python manage.py import_firewall_rules --dry-run

# Clear all existing rules and import fresh
python manage.py import_firewall_rules --clear

Admin Interface

Access the Django Admin to manage the firewall:

Firewall API Logs

• View all blocked/allowed IPs
• Block or allow IPs with one click
• Export logs to CSV
• Filter by date, blocked status, etc.

Firewall Path Rules (NEW)

• Create, edit, and delete blacklist/whitelist rules
• Set rule priorities for evaluation order
• Enable/disable rules temporarily
• Search by pattern or description
• Visual status indicators (✓/✗)
• Filter by rule type, enabled status, dates

Firewall IP Whitelist

• Create, edit, and delete trusted IP/network entries
• Support exact IPv4/IPv6 addresses and CIDR networks
• Enable/disable entries temporarily
• Search by IP/network or description
• Visual status indicators (✓/✗)

REST API

When Django REST Framework is installed, the following endpoints are available:

• GET /api/firewall/ - List all firewall logs
• GET /api/firewall/{id}/ - Get specific log entry

Endpoints require authentication and admin permissions.

Docker Support

For Docker environments, the app includes a script to automatically detect the host IP:

# The script is bundled at:
django_firewall/bin/get_firewall_host.sh

Configure the script path:

DJANGO_FIREWALL_GET_HOST_SCRIPT = "/app/django_firewall/bin/get_firewall_host.sh"

Cloudflare WAF Export

Generate Cloudflare-compatible WAF rules:

from django_firewall.endpoint_list import FirewallURLsExpression

print(FirewallURLsExpression)
# Output:
# (http.request.uri.path wildcard r"/admin/.htaccess") or
# (http.request.uri.path wildcard r"/.git/*") or
# ...

External Firewall Service

This app is designed to work with an external firewall service that accepts HTTP requests:

• GET /block?ip=1.2.3.4 - Block an IP
• GET /allow?ip=1.2.3.4 - Allow an IP

The external service should return HTTP 200 on success.

Security Considerations

• All IP addresses are validated to prevent SSRF attacks
• Blocking and allowing commands accept single IP addresses only
• IP whitelist entries accept exact IP addresses and CIDR networks
• The middleware runs early in the request cycle for best protection
• Admin access is restricted to superusers only

Changelog

See CHANGELOG.md for the full changelog.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.