Reel

Framework de simulação de phishing e conscientização de segurança com fluxos de trabalho configuráveis, gerenciamento de campanhas e proxy de credenciais opcional.

Início Rápido (USO OPERACIONAL)

1. Clone o repositório e entre nele com cd.
2. Execute ./deploy.sh - isso configurará os pré-requisitos para você, assumindo que você está no Ubuntu.
3. Execute ./start.sh --preload-ml. Isso iniciará os servidores e pré-carregará os modelos de ML que usamos.

Você obtém a interface de administração em http://localhost:8000 e o servidor de phishing em http://localhost:1234. Login padrão: admin / admin123. Altere a senha após o primeiro login.

Encaminhe a porta 8000 para sua máquina local via ssh para acessar o painel de administração. NÃO exponha o painel de administração nem o servidor flask (porta 1234) diretamente à internet.

O deploy.sh instalará um servidor caddy no mesmo host. Tudo é construído assumindo que você usará o caddy como proxy reverso. Você não precisa, mas aqui há dragões.

Flags opcionais para start.sh:

• --with-caddy — Inicia o Caddy via Docker (apenas para testes locais).
• --preload-ml — Pré-baixar o modelo de detecção de phishing (~1.3GB); evita o atraso no primeiro uso ao usar o plugin Phishing Detector.
• --reset-db — Redefine o banco de dados e reinicializa.
• --admin-only — Inicia apenas o servidor de administração (porta 8000).
• --phishing-only — Inicia apenas o servidor de phishing (porta 1234).
• --skip-init — Pula a inicialização do banco de dados.
• --skip-setup — Pula a configuração de venv/dependências; apenas carrega o .env e inicia os servidores.

Sem o start.sh, após instalar as dependências e inicializar o banco de dados, você pode executar ambos os servidores com: uv run python -m cli start.

Dependências

Python: Consulte requirements.txt. A stack principal inclui Flask, SQLAlchemy, Jinja2, Pydantic, Flask-Login, python-jose, passlib, cryptography e Flask-WTF. O plugin Phishing Detector usa transformers e torch. O proxy de credenciais usa Playwright; integrações opcionais usam OpenAI/Anthropic e boto3 (AWS Connect).

Desenvolvimento: requirements-dev.txt adiciona pytest, pytest-cov e ferramentas de teste relacionadas. Instale com uv pip install -r requirements-dev.txt para executar testes e cobertura.

Sistema (produção): O script de deploy tem como alvo Ubuntu/Debian. Ele instala uv, Caddy (proxy reverso) e pacotes de sistema como libmagic1. Para o proxy de credenciais, o start.sh executa uv run playwright install chromium para instalar o Chromium.

Scripts

deploy.sh

Preparação para produção no Ubuntu. Idempotente. Ele:

1. Verifica se é Ubuntu/Debian.
2. Instala pacotes de sistema (curl, ca-certificates, libmagic1, etc.).
3. Instala o uv se estiver ausente.
4. Instala o Caddy como proxy reverso (APT).
5. Cria um ambiente virtual e instala as dependências Python do requirements.txt.
6. Cria o .env a partir do .env.example se estiver ausente e gera SECRET_KEY e JWT_SECRET_KEY se não estiverem definidos.
7. Cria os diretórios necessários (storage/caddy/data, storage/caddy/config, storage/uploads, storage/templates, storage/assets, instance).
8. Opcionalmente inicializa o banco de dados com --init-db (executa uv run python -m cli init --force).

Ele não inicia a aplicação. Para produção: inicie o Caddy (proxy reverso) e depois inicie a aplicação com ./start.sh ou um gerenciador de processos para que todo o tráfego chegue à aplicação por meio do proxy.

start.sh

Inicialização de desenvolvimento e local. Ele:

1. Carrega o .env e garante SECRET_KEY e JWT_SECRET_KEY (gera-os se valores padrão estiverem presentes).
2. Verifica se o uv está instalado.
3. Cria um ambiente virtual se estiver ausente.
4. Instala as dependências do requirements.txt.
5. Executa uv run playwright install chromium para o proxy de credenciais.
6. Opcionalmente, pré-baixa o modelo de detecção de phishing com --preload-ml (~1.3GB).
7. Inicializa o banco de dados se nenhum arquivo de banco de dados existir (a menos que --skip-init). Use --reset-db para excluir e reinicializar.
8. Opcionalmente, inicia o Caddy via Docker com --with-caddy (apenas para testes locais).
9. Inicia os servidores: por padrão, admin e phishing via uv run python -m cli start; use --admin-only ou --phishing-only para executar apenas um.

Implantação em produção

Em produção, a aplicação deve ser executada atrás de um proxy reverso. Não exponha os servidores de desenvolvimento Flask diretamente à internet.

O proxy reverso é responsável pela terminação TLS, cabeçalhos Host corretos, roteamento de caminho e domínio, e pela separação do tráfego de administração do tráfego de campanha. A aplicação escuta em localhost ou em uma porta interna; o proxy lida com HTTPS público e encaminha para o servidor de administração (ex.: porta 8000) e para o servidor de phishing (ex.: porta 1234) de acordo com sua configuração.

Recomendado: Use o Caddy como proxy reverso. O deploy.sh instala o Caddy via APT. O projeto inclui exemplos de Caddyfile (ex.: Caddyfile.minimal). Após executar o deploy.sh, inicie o Caddy (ex.: caddy run --config /path/to/Caddyfile.minimal) e depois inicie a aplicação com ./start.sh ou um gerenciador de processos. Qualquer proxy reverso equivalente (nginx, Traefik, etc.) é aceitável, desde que a aplicação não seja exposta diretamente.

Intenção do projeto

Reel é um framework de simulação de phishing e conscientização de segurança. Operadores usam a interface de administração para gerenciar campanhas, fluxos de trabalho, templates e alvos. O servidor de phishing serve páginas de destino de campanhas e executa workflows—grafos de plugins baseados em nós—em cada solicitação.

Há dois pontos de entrada da aplicação em app.py: create_app() para o servidor de phishing e create_admin_app() para a interface de administração. As campanhas podem ser inbound (um visitante segue um link; os fluxos de trabalho GET e POST lidam com visualizações de página e envios de formulário) ou outbound (o sistema envia e-mails ou chamadas por meio de fluxos de trabalho de envio). O Caddy pode ser usado para roteamento de campanhas baseado em domínio. O proxy de credenciais usa Playwright para automação de navegador e reproduzir credenciais capturadas em sites-alvo.

Conceitos de fluxo de trabalho

Inbound

Um usuário visita uma URL de campanha (ex.: /<campaign_uid>). O servidor de phishing roteia pelo UID da campanha. Para solicitações GET, ele executa o workflow GET da campanha (ex.: renderizar página de destino, CAPTCHA); para solicitações POST, executa o workflow POST (ex.: validar entrada, capturar credenciais, redirecionar). Fluxos de trabalho são do tipo campaign e declaram suporte a métodos HTTP (GET, POST ou BOTH). O contexto de execução inclui campaign, request, session e variables. A resposta é obtida de chaves de contexto como _response_html, _response_redirect ou _response_json. Fluxos de trabalho inbound são usados para páginas de destino, CAPTCHA, captura de credenciais, redirecionamentos e registro de logs.

Outbound

Um operador executa um fluxo de trabalho de envio a partir da interface de administração, vinculado a uma campanha (o “Workflow” / fluxo de trabalho de envio da campanha). O executor de envio executa um único fluxo de trabalho do tipo sending: ele seleciona alvos (ex.: de CSV ou usuários rastreados), opcionalmente valida ou pré-renderiza o conteúdo e, em seguida, itera sobre os alvos—renderizando o e-mail, aplicando limites de taxa e enviando via um plugin (ex.: SMTP). Não há GET/POST de visitante; o fluxo de trabalho gera conteúdo e o envia para uma lista de alvos.

Resumo:

• Inbound: Orientado pelo visitante. Solicitações GET e POST acionam fluxos de trabalho da campanha. Usado para páginas de destino e manipulação de formulários.
• Outbound: Orientado pelo operador. Um único fluxo de trabalho de envio é executado no contexto de administração e envia em lote para os alvos (e-mail, voz, etc.).

Variáveis de fluxo de trabalho

Ao criar fluxos de trabalho, use a sintaxe {{variable}} para interpolação. Caminhos aninhados usam notação por pontos: {{nested.key}}.

Dados do alvo (de CSV / Loop)

Exemplo de CSV: email,first_name,last_name,company,landing_page → use {{target.email}}, {{target.first_name}}, {{target.company}}, {{target.custom_data.landing_page}}.

Campanha / Configuração

URLs

URL Obfuscator: Use url ou target.landing_page como fonte, ou interpole: http://{{target.ip}}/login.

Detector de Phishing HTML / BERT

Phishing Detector: Defina html_content como {{template_html}}, {{campaign.template_html}} ou {{email_html}}.

Saídas de plugins

Exemplo simples de fluxo de trabalho de envio

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

Tags típicas no template: {{target.email}}, {{target.first_name}}, {{target.last_name}}, {{target.custom_data.X}} para qualquer coluna extra do CSV.

Plugins

Os fluxos de trabalho são construídos a partir de nós; cada nó é um plugin com configuração. Os seguintes plugins integrados estão disponíveis.

Desenvolvimento

• Execute os testes: make test-fast ou ./run_tests.sh
• Testes com cobertura: make test-coverage ou ./run_tests.sh --coverage
• Lint: make lint
• Verificação de formatação: make format-check

Consulte o Makefile para alvos adicionais (divisões de testes unitários/integração/funcionais, init/reset do banco de dados, executar apenas o servidor de administração ou de phishing).

Documentação

• DEVELOPMENT.md — Instruções detalhadas para desenvolver plugins personalizados.
• AGENT_README.md — Para agentes de IA: conceitos do código, sistema de plugins, guias de estilo e prompts.