Reel

Фреймворк для симуляции фишинга и повышения осведомленности о безопасности с настраиваемыми рабочими процессами, управлением кампаниями и опциональным прокси для учетных данных.

Быстрый старт (для эксплуатации)

1. Клонируйте репозиторий и перейдите в него с помощью cd.
2. Запустите ./deploy.sh — он настроит необходимые зависимости, если вы используете Ubuntu.
3. Запустите ./start.sh --preload-ml. Это запустит серверы и предварительно загрузит используемые ML-модели.

Вы получаете админ-интерфейс по адресу http://localhost:8000 и фишинговый сервер по адресу http://localhost:1234. Логин по умолчанию: admin / admin123. Смените пароль после первого входа.

Пробросьте порт 8000 к себе локально по SSH, чтобы получить доступ к админ-панели. НЕ открывайте админ-панель или flask-сервер (порт 1234) напрямую в интернет.

deploy.sh установит сервер Caddy на тот же хост; всё построено в предположении, что вы будете использовать Caddy в качестве обратного прокси. Это не обязательно, но здесь обитают драконы.

Необязательные флаги для start.sh:

• --with-caddy — запуск Caddy через Docker (только для локального тестирования).
• --preload-ml — предварительная загрузка модели обнаружения фишинга (~1.3 ГБ); позволяет избежать задержки при первом использовании плагина Phishing Detector.
• --reset-db — сброс базы данных и повторная инициализация.
• --admin-only — запуск только админ-сервера (порт 8000).
• --phishing-only — запуск только фишингового сервера (порт 1234).
• --skip-init — пропуск инициализации базы данных.
• --skip-setup — пропуск настройки venv/зависимостей; просто загрузить .env и запустить серверы.

Без start.sh, после установки зависимостей и инициализации базы данных вы можете запустить оба сервера командой: uv run python -m cli start.

Зависимости

Python: Смотрите requirements.txt. Основной стек включает Flask, SQLAlchemy, Jinja2, Pydantic, Flask-Login, python-jose, passlib, cryptography и Flask-WTF. Плагин Phishing Detector использует transformers и torch. Прокси для учетных данных использует Playwright; опциональные интеграции используют OpenAI/Anthropic и boto3 (AWS Connect).

Разработка: requirements-dev.txt добавляет pytest, pytest-cov и связанные инструменты тестирования. Установите с помощью uv pip install -r requirements-dev.txt для запуска тестов и проверки покрытия.

Системные (продакшен): Скрипт развертывания рассчитан на Ubuntu/Debian. Он устанавливает uv, Caddy (обратный прокси) и системные пакеты, такие как libmagic1. Для прокси учетных данных start.sh выполняет uv run playwright install chromium для установки Chromium.

Скрипты

deploy.sh

Подготовка продакшен-окружения на Ubuntu. Идемпотентен. Он:

1. Проверяет наличие Ubuntu/Debian.
2. Устанавливает системные пакеты (curl, ca-certificates, libmagic1 и т.д.).
3. Устанавливает uv, если он отсутствует.
4. Устанавливает Caddy в качестве обратного прокси (APT).
5. Создает виртуальное окружение и устанавливает зависимости Python из requirements.txt.
6. Создает .env из .env.example, если он отсутствует, и генерирует SECRET_KEY и JWT_SECRET_KEY, если они не заданы.
7. Создает необходимые каталоги (storage/caddy/data, storage/caddy/config, storage/uploads, storage/templates, storage/assets, instance).
8. Опционально инициализирует базу данных с помощью --init-db (выполняет uv run python -m cli init --force).

Он не запускает приложение. Для продакшена: запустите Caddy (обратный прокси), затем запустите приложение с помощью ./start.sh или менеджера процессов, чтобы весь трафик поступал в приложение через прокси.

start.sh

Запуск для разработки и локального использования. Он:

1. Загружает .env и проверяет SECRET_KEY и JWT_SECRET_KEY (генерирует их, если присутствуют значения по умолчанию).
2. Проверяет, установлен ли uv.
3. Создает виртуальное окружение, если оно отсутствует.
4. Устанавливает зависимости из requirements.txt.
5. Выполняет uv run playwright install chromium для прокси учетных данных.
6. Опционально предварительно загружает модель обнаружения фишинга с помощью --preload-ml (~1.3 ГБ).
7. Инициализирует базу данных, если файл базы данных отсутствует (если не указан --skip-init). Используйте --reset-db для удаления и повторной инициализации.
8. Опционально запускает Caddy через Docker с помощью --with-caddy (только для локального тестирования).
9. Запускает серверы: по умолчанию и админ-сервер, и фишинговый через uv run python -m cli start; используйте --admin-only или для запуска одного.

Развертывание в продакшене

В продакшене приложение обязательно должно работать за обратным прокси. Не открывайте Flask-серверы разработки напрямую в интернет.

Обратный прокси отвечает за завершение TLS, корректные заголовки Host, маршрутизацию по путям и доменам, а также за разделение админ-трафика и трафика кампаний. Приложение прослушивает localhost или внутренний порт; прокси обрабатывает публичный HTTPS и перенаправляет трафик на админ-сервер (например, порт 8000) и фишинговый сервер (например, порт 1234) в соответствии с вашей конфигурацией.

Рекомендуется: используйте Caddy в качестве обратного прокси. deploy.sh устанавливает Caddy через APT. Проект включает примеры Caddyfile (например, Caddyfile.minimal). После выполнения deploy.sh запустите Caddy (например, caddy run --config /path/to/Caddyfile.minimal), а затем запустите приложение с помощью ./start.sh или менеджера процессов. Любой аналогичный обратный прокси (nginx, Traefik и т.п.) подойдет, если приложение не открыто напрямую.

Назначение проекта

Reel — это фреймворк для симуляции фишинга и повышения осведомленности о безопасности. Операторы используют админ-интерфейс для управления кампаниями, рабочими процессами, шаблонами и целями. Фишинговый сервер обслуживает целевые страницы кампаний и выполняет рабочие процессы — графы плагинов на основе узлов — при каждом запросе.

В app.py есть две точки входа в приложение: create_app() для фишингового сервера и create_admin_app() для админ-интерфейса. Кампании могут быть входящими (посетитель переходит по ссылке; GET- и POST-рабочие процессы обрабатывают просмотры страниц и отправку форм) или исходящими (система отправляет электронные письма или совершает звонки через отправляющие рабочие процессы). Caddy можно использовать для маршрутизации кампаний по доменам. Прокси учетных данных использует Playwright для автоматизации браузера с целью воспроизведения перехваченных учетных данных на целевых сайтах.

Концепции рабочих процессов

Входящие

Пользователь посещает URL кампании (например, /<campaign_uid>). Фишинговый сервер маршрутизирует по UID кампании. Для GET-запросов он выполняет GET-рабочий процесс кампании (например, рендер целевой страницы, CAPTCHA); для POST-запросов — POST-рабочий процесс (например, проверка ввода, перехват учетных данных, перенаправление). Рабочие процессы имеют тип campaign и объявляют поддержку HTTP-методов (GET, POST или BOTH). Контекст выполнения включает campaign, request, session и variables. Ответ берется из ключей контекста, таких как _response_html, _response_redirect или _response_json. Входящие рабочие процессы используются для целевых страниц, CAPTCHA, перехвата учетных данных, перенаправлений и логирования.

Исходящие

Оператор запускает отправляющий рабочий процесс из админ-интерфейса, привязанный к кампании («Workflow» / отправляющий рабочий процесс кампании). Исполнитель отправки выполняет один рабочий процесс типа sending: он выбирает цели (например, из CSV или отслеживаемых пользователей), опционально проверяет или предварительно рендерит контент, а затем перебирает цели — рендерит письмо, применяет ограничения скорости и отправляет через плагин (например, SMTP). Здесь нет GET/POST от посетителя; рабочий процесс генерирует контент и отправляет его списку целей.

Кратко:

• Входящие: управляются посетителем. GET- и POST-запросы запускают рабочие процессы кампании. Используются для целевых страниц и обработки форм.
• Исходящие: управляются оператором. Один отправляющий рабочий процесс выполняется в контексте админ-интерфейса и массово отправляет сообщения целям (электронная почта, голос и т.д.).

Переменные рабочих процессов

При создании рабочих процессов используйте синтаксис {{variable}} для интерполяции. Вложенные пути используют точечную нотацию: {{nested.key}}.

Данные цели (из CSV / цикла)

Пример CSV: email,first_name,last_name,company,landing_page → используйте {{target.email}}, {{target.first_name}}, {{target.company}}, {{target.custom_data.landing_page}}.

Кампания / Конфигурация

URLs

Обфускатор URL: используйте url или target.landing_page в качестве источника или интерполируйте: http://{{target.ip}}/login.

HTML / BERT Phishing Detector

Phishing Detector: установите html_content в {{template_html}}, {{campaign.template_html}} или {{email_html}}.

Выходные данные плагинов

Пример простого отправляющего рабочего процесса

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

Типичные теги в шаблоне: {{target.email}}, {{target.first_name}}, {{target.last_name}}, {{target.custom_data.X}} для любой дополнительной колонки CSV.

Плагины

Рабочие процессы строятся из узлов; каждый узел — это плагин с конфигурацией. Доступны следующие встроенные плагины.

Разработка

• Запуск тестов: make test-fast или ./run_tests.sh
• Тесты с покрытием: make test-coverage или ./run_tests.sh --coverage
• Линтинг: make lint
• Проверка форматирования: make format-check

Смотрите Makefile для дополнительных целей (разделение модульных/интеграционных/функциональных тестов, инициализация/сброс БД, запуск только админ- или фишингового сервера).

Документация

• DEVELOPMENT.md — Подробные инструкции по разработке пользовательских плагинов.
• AGENT_README.md — Для ИИ-агентов: концепции кодовой базы, система плагинов, руководства по стилю и промпты.