Metadata-Version: 2.4
Name: nai-security
Version: 1.5.2
Summary: Django security app - IP/email/country blocking, rate limiting, login tracking, auto-blocking
Author-email: Ali Nemati <alinemati@nemati.ai>
License: MIT
Project-URL: Homepage, https://github.com/nematiai/nai-security
Project-URL: Documentation, https://github.com/nematiai/nai-security#readme
Project-URL: Repository, https://github.com/nematiai/nai-security
Project-URL: Issues, https://github.com/nematiai/nai-security/issues
Keywords: django,security,ip-blocking,rate-limiting,country-blocking,email-blocking,login-tracking,geoip
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: django>=4.2
Requires-Dist: geoip2>=4.0
Requires-Dist: redis>=4.0
Provides-Extra: axes
Requires-Dist: django-axes>=6.0; extra == "axes"
Provides-Extra: ratelimit
Requires-Dist: django-ratelimit>=4.0; extra == "ratelimit"
Provides-Extra: import-export
Requires-Dist: django-import-export>=3.0; extra == "import-export"
Provides-Extra: unfold
Requires-Dist: django-unfold>=0.10; extra == "unfold"
Provides-Extra: all
Requires-Dist: django-axes>=6.0; extra == "all"
Requires-Dist: django-ratelimit>=4.0; extra == "all"
Requires-Dist: django-import-export>=3.0; extra == "all"
Requires-Dist: django-unfold>=0.10; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-django; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: ruff; extra == "dev"

# NAI Security

Django security package for IP blocking, country blocking, email blocking, rate limiting, and login tracking.

## Features

- **IP Blocking** - Block specific IPs manually or automatically
- **Country Blocking** - Block/allow countries using GeoIP
- **Email Blocking** - Block disposable emails and specific addresses
- **Domain Blocking** - Block email domains (disposable, spam, etc.)
- **User Agent Blocking** - Block bots, scrapers, attack tools
- **Rate Limiting** - Custom rate limit rules per endpoint
- **Login History** - Track user logins with anomaly detection
- **Auto-Blocking** - Automatically block IPs/countries based on attack patterns
- **Security Logs** - Comprehensive logging of all security events
- ✅ **Dynamic Login Attempt Limits** - Configurable max login attempts via admin panel (integrates with django-axes)

## Installation

```bash
pip install nai-security
```

Or install from GitHub:

```bash
pip install git+https://github.com/nematiai/nai-security.git
```

Or add to `requirements.txt`:

```
nai-security==1.5.1
```

Or from GitHub in requirements.txt:

```
git+https://github.com/nematiai/nai-security.git@main#egg=nai-security
```

## Quick Start

### 1. Add to INSTALLED_APPS

```python
INSTALLED_APPS = [
    ...
    "nai_security",
]
```

### 2. Add Middleware

```python
MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    ...
    "nai_security.middleware.SecurityMiddleware",  # After SecurityMiddleware
    ...
    "nai_security.middleware.RateLimitLoggingMiddleware",  # Near the end
]

### 3. Configure Settings

```python
# GeoIP database path
GEOIP_PATH = "/path/to/GeoLite2-Country.mmdb"

# Optional: Enable/disable middleware
SECURITY_MIDDLEWARE_ENABLED = True
RATELIMIT_MIDDLEWARE_ENABLED = True
```

### 4. Run Migrations

```bash
python manage.py makemigrations nai_security
python manage.py migrate
```

### 5. Download GeoIP Database

```bash
python manage.py download_geoip
```

## Dependencies

**Required:**
- Django >= 4.2
- geoip2 >= 4.0
- redis >= 4.0

**Optional:**
- django-axes >= 6.0 (login attempt tracking)
- django-ratelimit >= 4.0 (rate limiting)
- django-import-export >= 3.0 (admin import/export)
- django-unfold >= 0.10 (admin theme)

Install all optional dependencies:

```bash
pip install nai-security[all]
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `GEOIP_PATH` | `./geoip/GeoLite2-Country.mmdb` | Path to GeoIP database |
| `SECURITY_MIDDLEWARE_ENABLED` | `True` | Enable security middleware |
| `RATELIMIT_MIDDLEWARE_ENABLED` | `True` | Enable rate limit logging |

## Management Commands

```bash
# Download GeoIP database
python manage.py download_geoip

# Sync disposable email domains and bad bot lists
python manage.py sync_security_lists
python manage.py sync_security_lists --domains-only
python manage.py sync_security_lists --bots-only
```

## Celery Tasks

Add to your Celery beat schedule:

```python
CELERY_BEAT_SCHEDULE = {
    'security-auto-blocks': {
        'task': 'security.process_auto_blocks',
        'schedule': crontab(minute='*/5'),  # Every 5 minutes
    },
    'security-cleanup-expired': {
        'task': 'security.cleanup_expired_blocks',
        'schedule': crontab(minute=0, hour='*'),  # Every hour
    },
    'security-sync-lists': {
        'task': 'security.sync_security_lists',
        'schedule': crontab(minute=0, hour=0, day_of_week=0),  # Weekly
    },
    'security-daily-report': {
        'task': 'security.generate_security_report',
        'schedule': crontab(minute=0, hour=6),  # Daily at 6 AM
    },
}
```

## Models

| Model | Description |
|-------|-------------|
| `BlockedIP` | Blocked IP addresses |
| `BlockedCountry` | Blocked countries |
| `AllowedCountry` | Allowed countries (whitelist mode) |
| `BlockedEmail` | Blocked email addresses |
| `BlockedDomain` | Blocked email domains |
| `BlockedUserAgent` | Blocked user agents |
| `WhitelistedIP` | IPs that bypass all checks |
| `RateLimitRule` | Custom rate limit rules |
| `LoginHistory` | User login tracking |
| `SecurityLog` | Security event logs |
| `SecuritySettings` | Global settings (singleton) |

## Axes Integration

To enable dynamic login attempt control:

```python
# settings.py
AXES_HANDLER = 'nai_security.handlers.DynamicAxesHandler'
```

Now admins can change the lockout threshold in real-time via the Security Settings admin panel.

## License

MIT License

## Author

Ali Nemati - [NEMATI AI](https://nemati.ai)
```

