Metadata-Version: 2.4
Name: django-firewall
Version: 2.0.9
Summary: IP-based firewall protection for Django with path rule management.
Author-email: Visian Systems <contact@visiansystems.com>
License-Expression: MIT
Project-URL: Homepage, https://visiansystems.com
Project-URL: Project, https://gitlab.com/visian/infra-structure/django_firewall
Project-URL: Repository, https://gitlab.com/visian/infra-structure/django_firewall
Project-URL: Issues, https://gitlab.com/visian/infra-structure/django_firewall/-/issues
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Django :: 5.1
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.2
Requires-Dist: requests>=2.28
Requires-Dist: python-dotenv>=1.2.2
Provides-Extra: rest
Requires-Dist: djangorestframework>=3.14; extra == "rest"
Dynamic: license-file

# Django Firewall

[![PyPI](https://img.shields.io/pypi/v/django-firewall.svg)](https://pypi.org/project/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**:

```bash
pip install django_firewall
```

With optional Django REST Framework support:

```bash
pip install django_firewall[rest]
```

### Install from Git (Poetry)

```bash
poetry add django_firewall
```

With optional Django REST Framework support:

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

### Manual install

Copy the `django_firewall` directory to your project.

## Quick Start

### 1. Add to INSTALLED_APPS

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

### 2. Add middleware (optional but recommended)

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

### 3. Run migrations

```bash
python manage.py migrate django_firewall
```

### 4. Configure settings

```python
# 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

```python
# 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

```bash
# 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](django_firewall/FIREWALL_PATHS_README.md) - Comprehensive documentation
- [Quick Setup](django_firewall/SETUP_INSTRUCTIONS.md) - 3-step setup guide
- [Implementation](django_firewall/IMPLEMENTATION_SUMMARY.md) - 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:

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

Environment variables use comma-separated values:

```bash
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:

```bash
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:

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

Text file format:

```text
# 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

```bash
# 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

```bash
# 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:

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

Configure the script path:

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

## Cloudflare WAF Export

Generate Cloudflare-compatible WAF rules:

```python
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](CHANGELOG.md) for the full changelog.

## License

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