Reel

Marco de simulación de phishing y concienciación en seguridad con flujos de trabajo configurables, gestión de campañas y proxy de credenciales opcional.

Inicio rápido (USO OPS)

1. Clona el repositorio y entra en él con cd.
2. Ejecuta ./deploy.sh; esto configurará los requisitos previos por ti, asumiendo que estás en Ubuntu.
3. Ejecuta ./start.sh --preload-ml. Esto iniciará los servidores y precargará los modelos de ML que usamos.

Obtienes la interfaz de administración (Admin UI) en http://localhost:8000 y el servidor de phishing en http://localhost:1234. Inicio de sesión por defecto: admin / admin123. Cambia la contraseña después del primer inicio de sesión.

Reenvía el puerto 8000 a tu equipo local mediante SSH para acceder al panel de administración. NO expongas el panel de administración ni el servidor Flask (puerto 1234) directamente a Internet.

deploy.sh instalará un servidor Caddy en el mismo host; todo está construido asumiendo que usarás Caddy como proxy inverso. No es obligatorio, pero aquí hay dragones.

Banderas opcionales para start.sh:

• --with-caddy — Inicia Caddy mediante Docker (solo para pruebas locales).
• --preload-ml — Descarga previamente el modelo de detección de phishing (~1.3GB); evita la demora del primer uso al utilizar el plugin Phishing Detector.
• --reset-db — Restablece la base de datos y la reinicializa.
• --admin-only — Inicia solo el servidor de administración (puerto 8000).
• --phishing-only — Inicia solo el servidor de phishing (puerto 1234).
• --skip-init — Omite la inicialización de la base de datos.
• --skip-setup — Omite la configuración del venv/dependencias; solo carga .env e inicia los servidores.

Sin start.sh, después de instalar las dependencias e inicializar la base de datos, puedes ejecutar ambos servidores con: uv run python -m cli start.

Dependencias

Python: Consulta requirements.txt. El stack principal incluye Flask, SQLAlchemy, Jinja2, Pydantic, Flask-Login, python-jose, passlib, cryptography y Flask-WTF. El plugin Phishing Detector usa transformers y torch. El proxy de credenciales usa Playwright; las integraciones opcionales usan OpenAI/Anthropic y boto3 (AWS Connect).

Desarrollo: requirements-dev.txt añade pytest, pytest-cov y herramientas de prueba relacionadas. Instala con uv pip install -r requirements-dev.txt para ejecutar pruebas y cobertura.

Sistema (producción): El script de despliegue está dirigido a Ubuntu/Debian. Instala uv, Caddy (proxy inverso) y paquetes del sistema como libmagic1. Para el proxy de credenciales, start.sh ejecuta uv run playwright install chromium para instalar Chromium.

Scripts

deploy.sh

Preparación para producción en Ubuntu. Idempotente. Hace lo siguiente:

1. Comprueba que sea Ubuntu/Debian.
2. Instala paquetes del sistema (curl, ca-certificates, libmagic1, etc.).
3. Instala uv si no está presente.
4. Instala Caddy como proxy inverso (APT).
5. Crea un entorno virtual e instala las dependencias de Python desde requirements.txt.
6. Crea .env a partir de .env.example si no existe y genera SECRET_KEY y JWT_SECRET_KEY si no están definidas.
7. Crea los directorios requeridos (storage/caddy/data, storage/caddy/config, storage/uploads, storage/templates, storage/assets, instance).
8. Inicializa opcionalmente la base de datos con --init-db (ejecuta uv run python -m cli init --force).

No inicia la aplicación. Para producción: inicia Caddy (proxy inverso) y luego arranca la aplicación con ./start.sh o un administrador de procesos para que todo el tráfico llegue a la aplicación a través del proxy.

start.sh

Arranque de desarrollo y local. Hace lo siguiente:

1. Carga .env y garantiza SECRET_KEY y JWT_SECRET_KEY (las genera si hay valores por defecto presentes).
2. Verifica que uv esté instalado.
3. Crea un entorno virtual si falta.
4. Instala las dependencias desde requirements.txt.
5. Ejecuta uv run playwright install chromium para el proxy de credenciales.
6. Descarga opcionalmente por adelantado el modelo de detección de phishing con --preload-ml (~1.3GB).
7. Inicializa la base de datos si no existe ningún archivo de base de datos (salvo que se use --skip-init). Usa --reset-db para borrarla y reinicializarla.
8. Inicia opcionalmente Caddy mediante Docker con --with-caddy (solo para pruebas locales).
9. Inicia los servidores: por defecto tanto el de administración como el de phishing mediante uv run python -m cli start; usa --admin-only o para ejecutar solo uno.

Despliegue en producción

En producción, la aplicación debe ejecutarse detrás de un proxy inverso. No expongas los servidores de desarrollo de Flask directamente a Internet.

El proxy inverso es responsable de la terminación TLS, las cabeceras Host correctas, el enrutamiento por ruta y dominio, y de separar el tráfico de administración del tráfico de campañas. La aplicación escucha en localhost o en un puerto interno; el proxy gestiona el HTTPS público y reenvía al servidor de administración (p. ej. puerto 8000) y al servidor de phishing (p. ej. puerto 1234) según tu configuración.

Recomendado: Usa Caddy como proxy inverso. deploy.sh instala Caddy mediante APT. El proyecto incluye ejemplos de Caddyfile (p. ej. Caddyfile.minimal). Después de ejecutar deploy.sh, inicia Caddy (p. ej. caddy run --config /path/to/Caddyfile.minimal) y luego arranca la aplicación con ./start.sh o un administrador de procesos. Cualquier proxy inverso equivalente (nginx, Traefik, etc.) es aceptable siempre que la aplicación no esté expuesta directamente.

Propósito del proyecto

Reel es un marco de simulación de phishing y concienciación en seguridad. Los operadores usan la interfaz de administración (admin UI) para gestionar campañas, flujos de trabajo, plantillas y objetivos. El servidor de phishing sirve las páginas de aterrizaje de las campañas y ejecuta flujos de trabajo—grafos basados en nodos de plugins—en cada petición.

Hay dos puntos de entrada de la aplicación en app.py: create_app() para el servidor de phishing y create_admin_app() para la interfaz de administración. Las campañas pueden ser entrantes (inbound) (un visitante sigue un enlace; los flujos de trabajo GET y POST gestionan las vistas de página y los envíos de formularios) o salientes (outbound) (el sistema envía correos o llamadas mediante flujos de trabajo de envío). Caddy puede usarse para el enrutamiento de campañas basado en dominios. El proxy de credenciales usa Playwright para la automatización del navegador y reproducir las credenciales capturadas en los sitios objetivo.

Conceptos de flujos de trabajo

Inbound (entrante)

Un usuario visita una URL de campaña (p. ej. /<campaign_uid>). El servidor de phishing enruta por UID de campaña. Para peticiones GET ejecuta el flujo de trabajo GET de la campaña (p. ej. renderizar página de aterrizaje, CAPTCHA); para peticiones POST ejecuta el flujo de trabajo POST (p. ej. validar la entrada, capturar credenciales, redirigir). Los flujos de trabajo son de tipo campaign y declaran soporte de métodos HTTP (GET, POST o AMBOS). El contexto de ejecución incluye campaign, request, session y variables. La respuesta se toma de claves del contexto como _response_html, _response_redirect o _response_json. Los flujos de trabajo entrantes se usan para páginas de aterrizaje, CAPTCHA, captura de credenciales, redirecciones y registro de eventos.

Outbound (saliente)

Un operador ejecuta un flujo de trabajo de envío desde la interfaz de administración, vinculado a una campaña (el «Workflow» / flujo de trabajo de envío de la campaña). El ejecutor de envíos ejecuta un único flujo de trabajo de tipo sending: selecciona los objetivos (p. ej. desde CSV o usuarios rastreados), opcionalmente valida o pre-renderiza el contenido y luego itera sobre los objetivos—renderizando el correo, aplicando límites de tasa y enviando mediante un plugin (p. ej. SMTP). No hay GET/POST de visitante; el flujo de trabajo genera contenido y lo envía a una lista de objetivos.

Resumen:

• Inbound: Impulsado por el visitante. Las peticiones GET y POST disparan los flujos de trabajo de la campaña. Se usa para páginas de aterrizaje y manejo de formularios.
• Outbound: Impulsado por el operador. Un único flujo de trabajo de envío se ejecuta en el contexto de administración y envía por lotes a los objetivos (correo, voz, etc.).

Variables de los flujos de trabajo

Al construir flujos de trabajo, usa la sintaxis {{variable}} para la interpolación. Las rutas anidadas usan notación de puntos: {{nested.key}}.

Datos del objetivo (desde CSV / Bucle)

Ejemplo de CSV: email,first_name,last_name,company,landing_page → usa {{target.email}}, {{target.first_name}}, {{target.company}}, {{target.custom_data.landing_page}}.

Campaña / Configuración

URLs

Ofuscador de URL: Usa url o target.landing_page como fuente, o interpola: http://{{target.ip}}/login.

Detector de phishing HTML / BERT

Detector de phishing: Establece html_content a {{template_html}}, {{campaign.template_html}} o {{email_html}}.

Salidas de los plugins

Ejemplo de flujo de trabajo de envío simple

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

Etiquetas típicas en la plantilla: {{target.email}}, {{target.first_name}}, {{target.last_name}}, {{target.custom_data.X}} para cualquier columna CSV adicional.

Plugins

Los flujos de trabajo se construyen a partir de nodos; cada nodo es un plugin con configuración. Los siguientes plugins integrados están disponibles.

Desarrollo

• Ejecutar las pruebas: make test-fast o ./run_tests.sh
• Pruebas con cobertura: make test-coverage o ./run_tests.sh --coverage
• Lint: make lint
• Verificación de formato: make format-check

Consulta el Makefile para ver otros objetivos (división de pruebas unitarias/de integración/funcionales, init/reset de la base de datos, ejecutar solo el servidor de administración o de phishing).

Documentación

• DEVELOPMENT.md — Instrucciones detalladas para desarrollar plugins personalizados.
• AGENT_README.md — Para agentes de IA: conceptos del código base, sistema de plugins, guías de estilo y prompts.