Reel

Framework de simulation de phishing et de sensibilisation à la sécurité avec workflows configurables, gestion de campagnes et proxy d'identifiants optionnel.

Démarrage rapide (OPS USE)

1. Clonez le dépôt et faites cd dedans.
2. Exécutez ./deploy.sh - cela configurera les prérequis pour vous, en supposant que vous êtes sur Ubuntu.
3. Exécutez ./start.sh --preload-ml. Cela démarrera les serveurs et préchargera les modèles de ML que nous utilisons.

Vous obtenez l'interface d'administration sur http://localhost:8000 et le serveur de phishing sur http://localhost:1234. Connexion par défaut : admin / admin123. Changez le mot de passe après la première connexion.

Redirigez le port 8000 vers votre machine locale via SSH pour accéder au panneau d'administration. N'exposez PAS le panneau d'administration ni le serveur Flask (port 1234) directement sur Internet.

deploy.sh installera un serveur Caddy sur le même hôte ; tout est construit en supposant que vous utiliserez Caddy comme proxy inverse. Vous n'êtes pas obligé, mais ici il y a des dragons.

Options facultatives pour start.sh :

• --with-caddy — Démarre Caddy via Docker (tests locaux uniquement).
• --preload-ml — Pré-télécharge le modèle de détection de phishing (~1,3 Go) ; évite le délai de première utilisation avec le plugin Détecteur de phishing.
• --reset-db — Remet à zéro la base de données et la réinitialise.
• --admin-only — Démarre uniquement le serveur d'administration (port 8000).
• --phishing-only — Démarre uniquement le serveur de phishing (port 1234).
• --skip-init — Ignore l'initialisation de la base de données.
• --skip-setup — Ignore la configuration du venv/dépendances ; charge simplement .env et démarre les serveurs.

Sans start.sh, après avoir installé les dépendances et initialisé la base de données, vous pouvez lancer les deux serveurs avec : uv run python -m cli start.

Dépendances

Python : Voir requirements.txt. La pile de base comprend Flask, SQLAlchemy, Jinja2, Pydantic, Flask-Login, python-jose, passlib, cryptography et Flask-WTF. Le plugin Détecteur de phishing utilise transformers et torch. Le proxy d'identifiants utilise Playwright ; les intégrations optionnelles utilisent OpenAI/Anthropic et boto3 (AWS Connect).

Développement : requirements-dev.txt ajoute pytest, pytest-cov et les outils de test associés. Installez avec uv pip install -r requirements-dev.txt pour exécuter les tests et la couverture.

Système (production) : Le script de déploiement cible Ubuntu/Debian. Il installe uv, Caddy (proxy inverse) et des paquets système tels que libmagic1. Pour le proxy d'identifiants, start.sh exécute uv run playwright install chromium pour installer Chromium.

Scripts

deploy.sh

Préparation de la production sur Ubuntu. Idempotent. Il :

1. Vérifie la présence d'Ubuntu/Debian.
2. Installe les paquets système (curl, ca-certificates, libmagic1, etc.).
3. Installe uv s'il est manquant.
4. Installe Caddy comme proxy inverse (APT).
5. Crée un environnement virtuel et installe les dépendances Python depuis requirements.txt.
6. Crée .env à partir de .env.example s'il est manquant et génère SECRET_KEY et JWT_SECRET_KEY s'ils ne sont pas définis.
7. Crée les répertoires requis (storage/caddy/data, storage/caddy/config, storage/uploads, storage/templates, storage/assets, instance).
8. Initialise éventuellement la base de données avec --init-db (exécute uv run python -m cli init --force).

Il ne démarre pas l'application. En production : démarrez Caddy (proxy inverse), puis démarrez l'application avec ./start.sh ou un gestionnaire de processus afin que tout le trafic atteigne l'application via le proxy.

start.sh

Démarrage en développement et en local. Il :

1. Charge .env et garantit SECRET_KEY et JWT_SECRET_KEY (les génère si des valeurs par défaut sont présentes).
2. Vérifie que uv est installé.
3. Crée un environnement virtuel s'il est manquant.
4. Installe les dépendances depuis requirements.txt.
5. Exécute uv run playwright install chromium pour le proxy d'identifiants.
6. Pré-télécharge éventuellement le modèle de détection de phishing avec --preload-ml (~1,3 Go).
7. Initialise la base de données si aucun fichier de base de données n'existe (sauf avec --skip-init). Utilisez --reset-db pour supprimer et réinitialiser.
8. Démarre éventuellement Caddy via Docker avec --with-caddy (tests locaux uniquement).
9. Démarre les serveurs : par défaut, à la fois l'admin et le phishing via uv run python -m cli start ; utilisez --admin-only ou --phishing-only pour n'en lancer qu'un.

Déploiement en production

En production, l'application doit être exécutée derrière un proxy inverse. N'exposez pas les serveurs de développement Flask directement sur Internet.

Le proxy inverse est responsable de la terminaison TLS, des en-têtes Host corrects, du routage des chemins et des domaines, et de la séparation du trafic d'administration du trafic de campagne. L'application écoute sur localhost ou sur un port interne ; le proxy gère le HTTPS public et transmet au serveur d'administration (par exemple le port 8000) et au serveur de phishing (par exemple le port 1234) selon votre configuration.

Recommandé : Utilisez Caddy comme proxy inverse. deploy.sh installe Caddy via APT. Le projet inclut des exemples de Caddyfile (par exemple Caddyfile.minimal). Après avoir exécuté deploy.sh, démarrez Caddy (par exemple caddy run --config /path/to/Caddyfile.minimal), puis démarrez l'application avec ./start.sh ou un gestionnaire de processus. Tout proxy inverse équivalent (nginx, Traefik, etc.) est acceptable tant que l'application n'est pas exposée directement.

Objectif du projet

Reel est un framework de simulation de phishing et de sensibilisation à la sécurité. Les opérateurs utilisent l'interface d'administration pour gérer les campagnes, les workflows, les modèles et les cibles. Le serveur de phishing sert les pages de destination des campagnes et exécute des workflows — des graphes de plugins basés sur des nœuds — à chaque requête.

Il y a deux points d'entrée de l'application dans app.py : create_app() pour le serveur de phishing et create_admin_app() pour l'interface d'administration. Les campagnes peuvent être entrantes (un visiteur suit un lien ; les workflows GET et POST gèrent les vues de page et les soumissions de formulaires) ou sortantes (le système envoie des e-mails ou des appels via des workflows d'envoi). Caddy peut être utilisé pour le routage des campagnes par domaine. Le proxy d'identifiants utilise Playwright pour l'automatisation du navigateur afin de rejouer les identifiants capturés sur les sites cibles.

Concepts de workflow

Entrant

Un utilisateur visite une URL de campagne (par exemple /<campaign_uid>). Le serveur de phishing route par UID de campagne. Pour les requêtes GET, il exécute le workflow GET de la campagne (par exemple, rendre la page de destination, CAPTCHA) ; pour les requêtes POST, il exécute le workflow POST (par exemple, valider les entrées, capturer les identifiants, rediriger). Les workflows sont de type campagne et déclarent le support des méthodes HTTP (GET, POST ou BOTH). Le contexte d'exécution inclut campaign, request, session et variables. La réponse est tirée de clés de contexte telles que _response_html, _response_redirect ou _response_json. Les workflows entrants sont utilisés pour les pages de destination, les CAPTCHA, la capture d'identifiants, les redirections et la journalisation.

Sortant

Un opérateur exécute un workflow d'envoi depuis l'interface d'administration, lié à une campagne (le « Workflow » / workflow d'envoi de la campagne). L'exécuteur d'envoi exécute un seul workflow de type envoi : il sélectionne les cibles (par exemple depuis un CSV ou des utilisateurs suivis), valide ou pré-rend éventuellement le contenu, puis itère sur les cibles — en rendant l'e-mail, en appliquant des limites de débit et en envoyant via un plugin (par exemple SMTP). Il n'y a pas de GET/POST visiteur ; le workflow génère le contenu et l'envoie à une liste de cibles.

Résumé :

• Entrant : Piloté par le visiteur. Les requêtes GET et POST déclenchent les workflows de campagne. Utilisé pour les pages de destination et le traitement des formulaires.
• Sortant : Piloté par l'opérateur. Un seul workflow d'envoi s'exécute dans le contexte d'administration et envoie en masse aux cibles (e-mail, voix, etc.).

Variables de workflow

Lors de la création de workflows, utilisez la syntaxe {{variable}} pour l'interpolation. Les chemins imbriqués utilisent la notation par points : {{nested.key}}.

Données de cible (depuis CSV / Boucle)

Exemple CSV : email,first_name,last_name,company,landing_page → utilisez {{target.email}}, {{target.first_name}}, {{target.company}}, {{target.custom_data.landing_page}}.

Campagne / Configuration

URLs

Obfuscateur d'URL : Utilisez url ou target.landing_page comme source, ou interpolez : http://{{target.ip}}/login.

Détecteur de phishing HTML / BERT

Détecteur de phishing : Définissez html_content sur {{template_html}}, {{campaign.template_html}} ou {{email_html}}.

Sorties de plugins

Exemple simple de workflow d'envoi

Target Selector (CSV) → Loop (array_source: targets, item_key: target) → Render Template → SMTP Sender

Balises typiques dans le modèle : {{target.email}}, {{target.first_name}}, {{target.last_name}}, {{target.custom_data.X}} pour toute colonne CSV supplémentaire.

Plugins

Les workflows sont construits à partir de nœuds ; chaque nœud est un plugin avec une configuration. Les plugins intégrés suivants sont disponibles.

Développement

• Exécutez les tests : make test-fast ou ./run_tests.sh
• Tests avec couverture : make test-coverage ou ./run_tests.sh --coverage
• Lint : make lint
• Vérification du format : make format-check

Voir le Makefile pour des cibles supplémentaires (répartitions des tests unitaires/intégration/fonctionnels, init/réinitialisation de la base de données, exécution du serveur admin ou phishing uniquement).

Documentation

• DEVELOPMENT.md — Instructions détaillées pour développer des plugins personnalisés.
• AGENT_README.md — Pour les agents IA : concepts du codebase, système de plugins, guides de style et invites.