Metadata-Version: 2.4
Name: xeolux-securitykit
Version: 0.1.2
Summary: Package de sécurité Django configurable via interface web
Author-email: Xeolux <contact@xeolux.com>
License: MIT License
        
        Copyright (c) 2026 Xeolux
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/xeolux/xeolux-securitykit
Project-URL: Repository, https://github.com/xeolux/xeolux-securitykit
Project-URL: Issues, https://github.com/xeolux/xeolux-securitykit/issues
Keywords: django,security,middleware,protection,firewall,ddos
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Classifier: Topic :: Security
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=4.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-django; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Dynamic: license-file

# xeolux-securitykit

Package de sécurité Django configurable depuis une interface web intégrée.

[![PyPI version](https://img.shields.io/pypi/v/xeolux-securitykit.svg)](https://pypi.org/project/xeolux-securitykit/)
<!-- v0.1.2 -->
[![Python](https://img.shields.io/pypi/pyversions/xeolux-securitykit.svg)](https://pypi.org/project/xeolux-securitykit/)
[![Django](https://img.shields.io/badge/Django-4.x%20%7C%205.x-green)](https://www.djangoproject.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

---

## Présentation

`xeolux-securitykit` est un package Django professionnel permettant de protéger une application web de façon granulaire et configurable, sans toucher au code métier. Toute la configuration s'effectue depuis l'interface `/securitykit/` réservée aux superusers.

### Ce que le package apporte

| Fonctionnalité | Description |
|---|---|
| **Interface admin** | Dashboard `/securitykit/` accessible uniquement aux superusers |
| **50 modules** | Chaque module peut être activé/désactivé depuis l'interface |
| **Règles par route** | Politiques d'accès (allow / block / fake_404) par chemin URL |
| **Whitelist / Blacklist IP** | Contrôle des IP autorisées ou bloquées |
| **Rate limiting** | Limite des requêtes par IP, configurable par route |
| **Strict mode** | Mode de protection renforcé avec déverrouillage par token email |
| **Fake 404** | Masquer des routes sensibles avec une vraie réponse HTTP 404 |
| **Protection admin** | Changer l'URL de l'admin Django, bloquer l'accès non autorisé |
| **Headers HTTP** | Headers de sécurité automatiques (HSTS, CSP, X-Frame-Options…) |
| **Clés API** | Création et révocation de clés depuis l'interface |
| **Honeypot** | Champ piège invisible sur les formulaires contre les bots |
| **Diagnostics** | Vérification automatique de la configuration Django |

---

## Installation

```bash
pip install xeolux-securitykit
```

---

## Configuration

### 1. `settings.py` — minimum requis

```python
INSTALLED_APPS = [
    # ...
    "xeolux_securitykit",
]

MIDDLEWARE = [
    # ← En premier pour intercepter toutes les requêtes
    "xeolux_securitykit.middleware.XeoluxSecurityMiddleware",
    "django.middleware.security.SecurityMiddleware",
    # ... reste du middleware Django
]

# Minimum vital — tout le reste se configure depuis /securitykit/
XEOLUX_SECURITYKIT = {
    "ENABLED": True,
}
```

> **Principe** : `settings.py` ne sert que de bootstrap. Toute la configuration active (rate limit, headers, strict mode, admin secret URL…) est stockée en base de données et modifiable depuis `/securitykit/settings/`. Le package fonctionne même si la base n'est pas encore migrée (valeurs par défaut utilisées).

#### Overrides ponctuels dans settings.py

Si vous avez besoin d'un override fixe (CI, staging, secret en variable d'env) :

```python
XEOLUX_SECURITYKIT = {
    "ENABLED": True,
    # Override ponctuel — prend le dessus sur la DB seulement si la clé DB est absente
    "ADMIN_SECRET_URL": os.environ.get("ADMIN_URL", None),
}
```

### 2. `urls.py`

Ajoutez **une seule ligne** — le package gère lui-même ses sous-routes :

```python
from django.urls import path, include

urlpatterns = [
    path("", include("xeolux_securitykit.urls")),
    # ... vos autres routes
]
```

Le package enregistre automatiquement :
- `/securitykit/` → interface d'administration
- `/xk-unlock/<token>/` → page de déverrouillage dynamique (strict mode)

### 3. Migration

```bash
python manage.py migrate xeolux_securitykit
```

### 4. Collectstatic (optionnel)

```bash
python manage.py collectstatic
```

---

## Accès à l'interface

Rendez-vous sur **`/securitykit/`** avec un compte superuser.

> Si vous n'avez pas encore de superuser : `python manage.py createsuperuser`

---

## Modules — Activation et configuration

### Activer / désactiver un module

Depuis `/securitykit/` → **Modules** : chaque module dispose d'un bouton pour l'activer ou le désactiver individuellement. Un module désactivé est entièrement ignoré par le middleware.

### Configuration fine des modules

La plupart des modules ont des paramètres avancés configurables via `XEOLUX_SECURITYKIT` dans `settings.py`. Le toggle dans l'interface active/désactive le module ; ses paramètres fins restent dans les settings.

| Module | Clés settings associées |
|---|---|
| `rate_limit` | `RATE_LIMIT_WINDOW`, `RATE_LIMIT_MAX_REQUESTS` |
| `security_headers` | `SECURITY_HEADERS_ENABLED` |
| `honeypot` | `HONEYPOT_ENABLED` |
| `stealth_admin` | `STEALTH_ADMIN_ENABLED`, `ADMIN_SECRET_URL` |
| `strict_mode` | `STRICT_MODE_ENABLED`, `UNLOCK_CODE_TTL`, `UNLOCK_CODE_LENGTH` |
| `anti_ddos` | `ANTI_DDOS_ENABLED` |
| `fake_404` | `DEFAULT_RESPONSE`, `FAKE_404_TEMPLATE` |
| Tous | `EXEMPT_PATHS`, `CACHE_BACKEND`, `EMAIL_SUPER_ADMINS` |

### Liste des 50 modules

| Catégorie | Modules |
|---|---|
| Interface | `securitykit_dashboard`, `securitykit_ui`, `securitykit_self_protection` |
| Moteur | `module_registry`, `rules_engine`, `condition_engine`, `response_engine`, `fake_404`, `fake_response`, `lockout_safety`, `dry_run`, `rule_tester` |
| Routes | `route_discovery`, `route_rules` |
| Accès | `access_policies`, `ip_whitelist`, `ip_blacklist`, `permission_guard` |
| Config | `config_storage`, `config_import_export`, `security_profiles` |
| Admin | `stealth_admin`, `admin_secret_url` |
| Rate limit | `rate_limit`, `bruteforce_protection`, `slow_down`, `anti_ddos` |
| Détection | `suspicious_paths`, `file_access_guard`, `user_agent_blocker`, `bot_filter` |
| Formulaires | `honeypot`, `form_guard`, `csrf_guard` |
| API | `api_guard`, `api_key_manager`, `webhook_guard` |
| Headers | `security_headers`, `csp_manager`, `cookie_guard` |
| Requêtes | `method_guard`, `header_guard`, `payload_guard`, `querystring_guard`, `redirect_guard`, `cors_guard` |
| Strict mode | `strict_mode`, `strict_unlock` |
| Diagnostics | `settings_checker`, `safe_defaults` |

---

## Page 404/403 des visiteurs bloqués

SecurityKit utilise les **handlers natifs Django** (`page_not_found`, `permission_denied`).

Concrètement :
- Si vous avez un `404.html` dans vos templates → c'est **exactement** cette page qui s'affiche
- Si vous n'en avez pas → Django affiche sa page 404 par défaut
- **Il n'y a qu'une seule page 404 sur votre site** — celle que vous avez définie — ce qui ne trahit pas la présence d'un filtre de sécurité

> Deux pages 404 différentes (une pour les routes normales, une pour les routes bloquées) constitueraient une faille : elles prouveraient qu'une route existe mais est protégée. SecurityKit évite ça.

**Réponse par défaut** configurable depuis `/securitykit/settings/` (clé `DEFAULT_RESPONSE`) :

| Valeur | Comportement |
|---|---|
| `"fake_404"` | 404 native Django (votre `404.html`) *(défaut)* |
| `"403"` | 403 native Django (votre `403.html`) |
| `"empty"` | Réponse 200 vide (silencieuse) |
| `"json"` | JSON `{"detail": "Not found."}` (pour les APIs) |

---

## Strict Mode

Le strict mode bloque **tous les visiteurs non autorisés**. Deux niveaux :

| Niveau | Comportement |
|---|---|
| `strict` | Superusers + IPs whitelist passent |
| `lockdown` | Uniquement les IPs whitelist (niveau maximum) |

Quand le strict mode est activé :
1. Un **token aléatoire** est généré et stocké
2. Un **email est envoyé** aux superusers avec l'URL de déverrouillage : `/xk-unlock/<token>/`
3. Les visiteurs bloqués voient la **page de maintenance** (HTTP 503)
4. L'URL de déverrouillage change à chaque activation

**Commande de secours** (si accès web impossible) :

```bash
python manage.py securitykit_unlock --force
```

---

## Commandes de management

```bash
# Diagnostics et vérification de la configuration Django
python manage.py securitykit_check

# Désactiver le strict mode (secours terminal)
python manage.py securitykit_unlock

# Forcer la désactivation sans token
python manage.py securitykit_unlock --force

# Activer le strict mode depuis le terminal
python manage.py securitykit_strict_on

# Désactiver le strict mode depuis le terminal
python manage.py securitykit_strict_off

# Exporter la configuration (routes, règles, whitelist…)
python manage.py securitykit_export_config --output config.json

# Importer une configuration
python manage.py securitykit_import_config --input config.json
```

---

## Pages de l'interface

| URL | Description |
|---|---|
| `/securitykit/` | Dashboard général |
| `/securitykit/modules/` | Activation/désactivation des 50 modules |
| `/securitykit/routes/` | Gestion des routes protégées et leurs règles |
| `/securitykit/whitelist/` | IPs et CIDR autorisés |
| `/securitykit/blacklist/` | IPs et CIDR bloqués |
| `/securitykit/api-keys/` | Clés API |
| `/securitykit/strict-mode/` | Strict mode et token de déverrouillage |
| `/securitykit/diagnostics/` | Diagnostics de configuration Django |
| `/securitykit/rule-tester/` | Simulation de règles (dry run) |
| `/securitykit/profiles/` | Profils de sécurité prédéfinis |
| `/securitykit/config/export/` | Export de la configuration |
| `/securitykit/config/import/` | Import de la configuration |

---

## Avertissement

Ce package protège au niveau **applicatif Django**. Il ne peut pas absorber un DDoS réseau volumétrique. Pour une protection réseau complète, utilisez un WAF ou un CDN en amont (Cloudflare, Nginx rate limiting, etc.).

---

## Licence

MIT — Copyright 2026 Xeolux


### Fonctionnalités principales

- **Fake 404 configurable** : masquer n'importe quelle route avec une vraie réponse HTTP 404
- **Interface `/securitykit/`** : gestion complète depuis le navigateur
- **Règles par route** : politiques d'accès par URL
- **Whitelist / Blacklist IP** : contrôle des IP autorisées ou bloquées
- **Rate limiting** : limitation des requêtes par IP/route/utilisateur
- **Protection admin** : cacher `/admin/` aux non-autorisés
- **Strict mode** : mode de protection renforcé avec unlock par code email
- **Anti-abus applicatif** : détection bots, bruteforce, scan de routes
- **Headers de sécurité** : renforcement automatique des headers HTTP
- **Gestion des clés API** : création et révocation depuis l'interface
- **Diagnostics Django** : vérification de la configuration de sécurité

---

## Installation

```bash
pip install xeolux-securitykit
```

### Configuration `settings.py`

```python
INSTALLED_APPS = [
    # ...
    "xeolux_securitykit",
]

MIDDLEWARE = [
    # Placer en début de liste pour intercepter toutes les requêtes
    "xeolux_securitykit.middleware.XeoluxSecurityMiddleware",
    # ...
    "django.middleware.security.SecurityMiddleware",
    # ...
]

XEOLUX_SECURITYKIT = {
    "ENABLED": True,
    "DEFAULT_RESPONSE": "fake_404",
    "FAKE_404_TEMPLATE": "xeolux_securitykit/fake_404.html",
    "SECURITYKIT_PATH": "/securitykit/",
    "STRICT_UNLOCK_PATH": "/whitelistkit/unlockstrictmode/",
    "SELF_PROTECTION_ENABLED": True,
    "SUPERUSER_ONLY": True,
    "LOCKOUT_SAFETY_ENABLED": True,
    "STRICT_MODE_ENABLED": True,
    "ANTI_DDOS_ENABLED": True,
    "EMAIL_SUPER_ADMINS": True,
}
```

### Configuration `urls.py`

```python
from django.urls import path, include

urlpatterns = [
    path("", include("xeolux_securitykit.urls")),
    # ... vos autres routes
]
```

> Le package gère ses propres préfixes : l'interface est à `/securitykit/` et la page de déverrouillage dynamique à `/xk-unlock/<token>/`.

### Migration

```bash
python manage.py migrate xeolux_securitykit
```

---

## Commandes de management

```bash
# Diagnostics complets
python manage.py securitykit_check

# Désactiver le strict mode depuis le terminal (secours)
python manage.py securitykit_unlock

# Activer le strict mode manuellement
python manage.py securitykit_strict_on

# Désactiver le strict mode manuellement
python manage.py securitykit_strict_off

# Exporter la configuration
python manage.py securitykit_export_config --output config.json

# Importer une configuration
python manage.py securitykit_import_config --input config.json
```

---

## Accès à l'interface

Accessible sur `/securitykit/` — nécessite d'être superuser.

Pour déverrouiller le strict mode depuis le navigateur :
`/whitelistkit/unlockstrictmode/`

---

## Architecture des modules

Le package est organisé en 50 modules couvrant :

| Catégorie | Modules |
|---|---|
| Interface | dashboard, ui, self_protection |
| Moteur | rules_engine, condition_engine, response_engine |
| Accès | ip_whitelist, ip_blacklist, access_policies |
| Fake 404 | fake_404, fake_response |
| Admin | stealth_admin, admin_secret_url |
| API | api_guard, api_key_manager, webhook_guard |
| Rate limit | rate_limit, bruteforce_protection, slow_down |
| Headers | security_headers, csp_manager, cookie_guard |
| Formulaires | form_guard, honeypot, csrf_guard |
| Strict mode | strict_mode, strict_unlock, anti_ddos |
| Diagnostics | settings_checker, safe_defaults |

---

## Avertissement

Ce package protège au niveau **applicatif Django**. Il ne peut pas bloquer un DDoS réseau massif. Pour une protection réseau, utilisez un WAF ou un CDN en amont (Cloudflare, Nginx, etc.).

---

## Licence

MIT — Copyright 2026 Xeolux
