Reel

Phishing-Simulation und Framework für Sicherheitsbewusstsein mit konfigurierbaren Workflows, Kampagnenverwaltung und optionalem Credential-Proxy.

Quickstart (OPS-EINSATZ)

1. Klone das Repository und wechsle mit cd hinein.
2. Führe ./deploy.sh aus – dies konfiguriert die Voraussetzungen für dich, vorausgesetzt du verwendest Ubuntu.
3. Führe ./start.sh --preload-ml aus. Dies startet die Server und lädt die von uns verwendeten ML-Modelle vorab.

Du erreichst die Admin-Oberfläche unter http://localhost:8000 und den Phishing-Server unter http://localhost:1234. Standard-Login: admin / admin123. Ändere das Passwort nach der ersten Anmeldung.

Leite Port 8000 per SSH auf dein lokales System weiter, um auf das Admin-Panel zuzugreifen. Setze das Admin-Panel oder den Flask-Server (Port 1234) NICHT direkt dem Internet aus.

deploy.sh installiert einen Caddy-Server auf demselben Host. Alles ist darauf ausgelegt, dass du Caddy als Reverse-Proxy verwendest. Du musst es nicht tun, aber hier gibt es Drachen.

Optionale Flags für start.sh:

• --with-caddy — Startet Caddy über Docker (nur für lokale Tests).
• --preload-ml — Lädt das Phishing-Erkennungsmodell vorab herunter (~1,3 GB); vermeidet Verzögerungen bei der ersten Verwendung des Phishing-Detector-Plugins.
• --reset-db — Setzt die Datenbank zurück und initialisiert sie neu.
• --admin-only — Startet nur den Admin-Server (Port 8000).
• --phishing-only — Startet nur den Phishing-Server (Port 1234).
• --skip-init — Überspringt die Datenbankinitialisierung.
• --skip-setup — Überspringt die Einrichtung von venv/Abhängigkeiten; lädt nur .env und startet die Server.

Ohne start.sh kannst du nach der Installation der Abhängigkeiten und der Initialisierung der Datenbank beide Server mit uv run python -m cli start starten.

Abhängigkeiten

Python: Siehe requirements.txt. Der Kern-Stack umfasst Flask, SQLAlchemy, Jinja2, Pydantic, Flask-Login, python-jose, passlib, cryptography und Flask-WTF. Das Phishing-Detector-Plugin verwendet transformers und torch. Der Credential-Proxy verwendet Playwright; optionale Integrationen verwenden OpenAI/Anthropic und boto3 (AWS Connect).

Entwicklung: requirements-dev.txt fügt pytest, pytest-cov und zugehörige Testwerkzeuge hinzu. Installiere mit uv pip install -r requirements-dev.txt, um Tests und Testabdeckung auszuführen.

System (Produktion): Das Deploy-Skript zielt auf Ubuntu/Debian. Es installiert uv, Caddy (Reverse-Proxy) und Systempakete wie libmagic1. Für den Credential-Proxy führt start.sh uv run playwright install chromium aus, um Chromium zu installieren.

Skripte

deploy.sh

Produktionsvorbereitung auf Ubuntu. Idempotent. Es:

1. Prüft auf Ubuntu/Debian.
2. Installiert Systempakete (curl, ca-certificates, libmagic1 usw.).
3. Installiert uv, falls es fehlt.
4. Installiert Caddy als Reverse-Proxy (APT).
5. Erstellt eine virtuelle Umgebung und installiert Python-Abhängigkeiten aus requirements.txt.
6. Erstellt .env aus .env.example, falls es fehlt, und generiert SECRET_KEY und JWT_SECRET_KEY, falls diese nicht gesetzt sind.
7. Erstellt die erforderlichen Verzeichnisse (storage/caddy/data, storage/caddy/config, storage/uploads, storage/templates, storage/assets, instance).
8. Initialisiert optional die Datenbank mit --init-db (führt uv run python -m cli init --force aus).

Es startet die Anwendung nicht. Für die Produktion: Starte Caddy (Reverse-Proxy) und starte dann die App mit ./start.sh oder einem Prozessmanager, sodass der gesamte Datenverkehr über den Proxy zur App gelangt.

start.sh

Entwicklung und lokaler Start. Es:

1. Lädt .env und stellt sicher, dass SECRET_KEY und JWT_SECRET_KEY vorhanden sind (generiert sie, wenn Standardwerte vorliegen).
2. Überprüft, ob uv installiert ist.
3. Erstellt eine virtuelle Umgebung, falls sie fehlt.
4. Installiert Abhängigkeiten aus requirements.txt.
5. Führt uv run playwright install chromium für den Credential-Proxy aus.
6. Lädt optional das Phishing-Erkennungsmodell mit --preload-ml vorab herunter (~1,3 GB).
7. Initialisiert die Datenbank, wenn keine Datenbankdatei vorhanden ist (außer bei --skip-init). Verwende --reset-db, um zu löschen und neu zu initialisieren.
8. Startet optional Caddy über Docker mit --with-caddy (nur lokale Tests).
9. Startet die Server: standardmäßig sowohl Admin als auch Phishing über uv run python -m cli start; verwende --admin-only oder , um nur einen zu starten.

Produktionsbereitstellung

In der Produktion muss die Anwendung hinter einem Reverse-Proxy laufen. Setze die Flask-Entwicklungsserver nicht direkt dem Internet aus.

Der Reverse-Proxy ist verantwortlich für TLS-Terminierung, korrekte Host-Header, Pfad- und Domänen-Routing sowie die Trennung von Admin- und Kampagnenverkehr. Die App lauscht auf localhost oder einem internen Port; der Proxy übernimmt öffentliches HTTPS und leitet je nach Konfiguration an den Admin-Server (z. B. Port 8000) und den Phishing-Server (z. B. Port 1234) weiter.

Empfohlen: Verwende Caddy als Reverse-Proxy. deploy.sh installiert Caddy über APT. Das Projekt enthält Caddyfile-Beispiele (z. B. Caddyfile.minimal). Starte nach der Ausführung von deploy.sh Caddy (z. B. caddy run --config /path/to/Caddyfile.minimal) und starte dann die Anwendung mit ./start.sh oder einem Prozessmanager. Jeder gleichwertige Reverse-Proxy (nginx, Traefik usw.) ist akzeptabel, solange die App nicht direkt exponiert wird.

Projektabsicht

Reel ist ein Framework für Phishing-Simulationen und Sicherheitsbewusstsein. Betreiber verwenden die Admin-Oberfläche, um Kampagnen, Workflows, Vorlagen und Ziele zu verwalten. Der Phishing-Server stellt Kampagnen-Landingpages bereit und führt bei jeder Anfrage Workflows aus – knotenbasierte Graphen von Plugins.

Es gibt zwei Anwendungseinstiegspunkte in app.py: create_app() für den Phishing-Server und create_admin_app() für die Admin-Oberfläche. Kampagnen können inbound (ein Besucher folgt einem Link; GET- und POST-Workflows verarbeiten Seitenaufrufe und Formularübermittlungen) oder outbound sein (das System sendet E-Mails oder Anrufe über Sende-Workflows). Caddy kann für das domänenbasierte Routing von Kampagnen verwendet werden. Der Credential-Proxy verwendet Playwright für die Browser-Automatisierung, um erfasste Anmeldedaten auf Zielseiten erneut abzuspielen.

Workflow-Konzepte

Inbound

Ein Benutzer besucht eine Kampagnen-URL (z. B. /<campaign_uid>). Der Phishing-Server leitet anhand der Kampagnen-UID weiter. Bei GET-Anfragen führt er den GET-Workflow der Kampagne aus (z. B. Landingpage rendern, CAPTCHA); bei POST-Anfragen führt er den POST-Workflow aus (z. B. Eingaben validieren, Anmeldedaten erfassen, weiterleiten). Workflows sind vom Typ campaign und deklarieren die unterstützte HTTP-Methode (GET, POST oder BOTH). Der Ausführungskontext umfasst campaign, request, session und variables. Die Antwort wird aus Kontextschlüsseln wie _response_html, _response_redirect oder _response_json übernommen. Inbound-Workflows werden für Landingpages, CAPTCHA, Erfassung von Anmeldedaten, Weiterleitungen und Protokollierung verwendet.

Outbound

Ein Betreiber führt über die Admin-Oberfläche einen Sende-Workflow aus, der mit einer Kampagne verknüpft ist (der „Workflow“ / Sende-Workflow der Kampagne). Der Sende-Executor führt einen einzelnen Workflow vom Typ sending aus: Er wählt Ziele aus (z. B. aus CSV oder verfolgten Benutzern), validiert oder rendert Inhalte optional vorab und iteriert dann über die Ziele – rendert die E-Mail, wendet Ratenbegrenzungen an und sendet über ein Plugin (z. B. SMTP). Es gibt keinen Besucher-GET/POST; der Workflow erzeugt Inhalte und sendet sie an eine Liste von Zielen.

Zusammenfassung:

• Inbound: Besuchergesteuert. GET- und POST-Anfragen lösen Kampagnen-Workflows aus. Werden für Landingpages und Formularverarbeitung verwendet.
• Outbound: Betreibergesteuert. Ein einzelner Sende-Workflow läuft im Admin-Kontext und sendet massenhaft an Ziele (E-Mail, Sprache usw.).

Workflow-Variablen

Beim Erstellen von Workflows verwende die Syntax {{variable}} zur Interpolation. Verschachtelte Pfade verwenden Punktnotation: {{nested.key}}.

Zieldaten (aus CSV / Schleife)

CSV-Beispiel: email,first_name,last_name,company,landing_page → verwende {{target.email}}, {{target.first_name}}, {{target.company}}, {{target.custom_data.landing_page}}.

Kampagne / Konfiguration

URLs

URL-Verschleierer: Verwende url oder target.landing_page als Quelle oder interpoliere: http://{{target.ip}}/login.

HTML / BERT-Phishing-Detektor

Phishing-Detektor: Setze html_content auf {{template_html}}, {{campaign.template_html}} oder {{email_html}}.

Plugin-Ausgaben

Einfaches Beispiel für einen Sende-Workflow

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

Typische Tags in der Vorlage: {{target.email}}, {{target.first_name}}, {{target.last_name}}, {{target.custom_data.X}} für jede zusätzliche CSV-Spalte.

Plugins

Workflows werden aus Knoten aufgebaut; jeder Knoten ist ein Plugin mit Konfiguration. Die folgenden integrierten Plugins sind verfügbar.

Entwicklung

• Tests ausführen: make test-fast oder ./run_tests.sh
• Tests mit Abdeckung: make test-coverage oder ./run_tests.sh --coverage
• Lint: make lint
• Formatprüfung: make format-check

Siehe Makefile für weitere Ziele (Aufteilung in Unit-/Integrations-/Funktionstests, DB-Init/Reset, nur Admin- oder Phishing-Server starten).

Dokumentation

• DEVELOPMENT.md — Detaillierte Anleitung zur Entwicklung benutzerdefinierter Plugins.
• AGENT_README.md — Für KI-Agenten: Codebasis-Konzepte, Plugin-System, Styleguides und Prompts.