trustedsec/Reel

# Reel 钓鱼模拟与安全意识框架，提供可配置的工作流、活动管理以及可选的凭据代理。 ## 快速开始（OPS 使用） 1. 克隆此代码库并 `cd` 进入其中。 2. 运行 `./deploy.sh` - 假设您正在使用 Ubuntu，这将为您配置前置依赖。 3. 运行 `./start.sh --preload-ml`。这将启动服务器并预加载我们使用的机器学习模型。 您可以通过 http://localhost:8000 访问管理后台 UI，以及 http://localhost:1234 访问钓鱼服务器。默认登录账号：`admin` / `admin123`。首次登录后请修改密码。 通过 SSH 将 8000 端口转发到本地以访问管理面板。切勿将管理面板或 Flask 服务器（端口 1234）直接暴露在公网。 `deploy.sh` 将在同一主机上安装 Caddy 服务器，所有构建均假定您会使用 Caddy 作为反向代理。您并非必须如此，但若不这样做，后果自负。 **`start.sh` 的可选标志：** - `--with-caddy` — 通过 Docker 启动 Caddy（仅用于本地测试）。 - `--preload-ml` — 预先下载钓鱼检测模型（约 1.3GB）；避免首次使用 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](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](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. 通过 APT 安装 Caddy 作为反向代理。 5. 创建虚拟环境并从 `requirements.txt` 安装 Python 依赖。 6. 如果缺失，则从 `.env.example` 创建 `.env`，并在未设置时生成 `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.3GB）。 7. 如果数据库文件不存在，则初始化数据库（除非使用了 `--skip-init`）。使用 `--reset-db` 可删除并重新初始化。 8. 可选地通过 `--with-caddy` 借助 Docker 启动 Caddy（仅用于本地测试）。 9. 启动服务器：默认情况下通过 `uv run python -m cli start` 同时启动管理端和钓鱼端；使用 `--admin-only` 或 `--phishing-only` 仅运行其中一个。 ## 生产环境部署 在生产环境中，应用程序**必须**在反向代理后运行。切勿将 Flask 开发服务器直接暴露在公网。 反向代理负责 TLS 终端、正确的 Host 标头、路径和域名路由，以及将管理流量与活动流量分离开来。应用程序监听 localhost 或内部端口；代理处理公共 HTTPS，并根据您的配置将其转发到管理服务器（例如端口 8000）和钓鱼服务器（例如端口 1234）。 **建议：** 使用 Caddy 作为反向代理。`deploy.sh` 会通过 APT 安装 Caddy。项目包含 Caddyfile 示例（例如 [Caddyfile.minimal](Caddyfile.minimal)）。运行 `deploy.sh` 后，启动 Caddy（例如 `caddy run --config /path/to/Caddyfile.minimal`），然后使用 `./start.sh` 或进程管理器启动应用程序。只要应用程序不直接暴露，任何等效的反向代理（Nginx、Traefik 等）均可接受。 ## 项目意图 Reel 是一个钓鱼模拟与安全意识框架。操作员使用**管理后台 UI** 来管理活动、工作流、模板和目标。**钓鱼服务器**提供活动落地页，并在每次请求时运行**工作流**——由节点组成的插件图表。 [app.py](app.py) 中有两个应用程序入口点：用于钓鱼服务器的 `create_app()` 和用于管理后台 UI 的 `create_admin_app()`。活动可以是**入站**（访问者点击链接；GET 和 POST 工作流处理页面浏览和表单提交）或**出站**（系统通过发送工作流发送电子邮件或拨打电话）。Caddy 可用于基于域名的活动路由。凭据代理使用 Playwright 进行浏览器自动化，在目标站点上重放捕获的凭据。 ## 工作流概念 ### 入站 用户访问活动 URL（例如 `/`）。钓鱼服务器通过活动 UID 进行路由。对于 GET 请求，它会运行活动的 **GET 工作流**（例如渲染落地页、CAPTCHA）；对于 POST 请求，它会运行 **POST 工作流**（例如验证输入、捕获凭据、重定向）。工作流类型为 **campaign**，并声明支持的 HTTP 方法（GET、POST 或 BOTH）。执行上下文包括 `campaign`、`request`、`session` 和 `variables`。响应取自上下文键，例如 `_response_html`、`_response_redirect` 或 `_response_json`。入站工作流用于落地页、CAPTCHA、凭据捕获、重定向和日志记录。 ### 出站 操作员从管理后台 UI 运行链接到活动的**发送工作流**（即活动的“工作流”/发送工作流）。发送执行器运行类型为 **sending** 的单个工作流：它选择目标（例如从 CSV 或被追踪的用户中），可选择地验证或预渲染内容，然后遍历目标——渲染电子邮件、应用速率限制并通过插件（例如 SMTP）发送。没有访问者的 GET/POST 请求；工作流生成内容并将其发送到目标列表。 **总结：** - **入站：** 访问者驱动。GET 和 POST 请求触发活动工作流。用于落地页和表单处理。 - **出站：** 操作员驱动。在管理上下文中运行单个发送工作流，并批量发送给目标（电子邮件、语音等）。 ## 工作流变量 在构建工作流时，请使用 `{{variable}}` 语法进行插值。嵌套路径使用点表示法：`{{nested.key}}`。 ### 目标数据（来自 CSV / 循环） | 变量 | 描述 | |----------|-------------| | `{{target}}` | 当前循环迭代的完整目标对象 | | `{{target.email}}` | 目标电子邮件 | | `{{target.first_name}}` | 名字 | | `{{target.last_name}}` | 姓氏 | | `{{target.custom_data}}` | 包含其他 CSV 列的字典 | | `{{target.custom_data.column_name}}` | 任何额外的 CSV 列（例如 `{{target.custom_data.company}}`、`{{target.custom_data.landing_page}}`） | | `{{target.name}}` | `first_name` 或 `target.first_name` 的简写 | | `{{target_name}}` | 与 `target.name` 相同（别名） | | `{{target_email}}` | 与 `target.email` 相同（别名） | | `{{_loop_index}}` | 当前循环索引（从 0 开始） | **CSV 示例：** `email,first_name,last_name,company,landing_page` → 使用 `{{target.email}}`、`{{target.first_name}}`、`{{target.company}}`、`{{target.custom_data.landing_page}}`。 ### 活动 / 配置 | 变量 | 描述 | |----------|-------------| | `{{campaign.id}}` | 活动 ID | | `{{campaign.uid}}` | 活动 UID | | `{{campaign.name}}` | 活动名称 | | `{{campaign.template_html}}` | 活动模板 HTML | | `{{url}}` | 活动落地页 URL | | `{{campaign_id}}` | 活动 ID | | `{{variables}}` | 活动变量字典 | ### URL | 变量 | 描述 | |----------|-------------| | `{{url}}` | 活动落地页 URL（通过配置或默认设置） | | `{{target.landing_page}}` | 如果 CSV 中存在 `landing_page` | | `{{target.custom_data.landing_page}}` | 当 `landing_page` 位于 custom_data 中时，同上 | | `{{target.ip}}` | 如果 `ip` 位于 CSV 或自定义数据中 | **URL Obfuscator：** 使用 `url` 或 `target.landing_page` 作为源，或进行插值：`http://{{target.ip}}/login`。 ### HTML / BERT Phishing Detector | 变量 | 描述 | |----------|-------------| | `{{template_html}}` | 渲染后的 HTML | | `{{campaign.template_html}}` | 活动模板 HTML | | `{{email_html}}` | 渲染后的电子邮件 HTML（在 Render Template 之后） | | `{{body_html}}` | 电子邮件正文 HTML | **Phishing Detector：** 将 `html_content` 设置为 `{{template_html}}`、`{{campaign.template_html}}` 或 `{{email_html}}`。 ### 插件输出 | 变量 | 描述 | |----------|-------------| | `{{phishing_detection.is_phishing}}` | BERT 判定的 True/False | | `{{phishing_detection.confidence}}` | BERT 置信度得分 | | `{{captured_credentials.username}}` | 仅限入站 | | `{{captured_credentials.password}}` | 仅限入站 | | `{{_email_sent}}` | 表示 SMTP 发送成功 | ### 简单的发送工作流示例 ``` 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 列。 ## 插件 工作流由节点构建；每个节点都是一个带有配置的插件。以下是可用的内置插件。 | 插件 | 用途 | |--------|---------| | **CAPTCHA** | Cloudflare Turnstile：验证 token 和/或渲染小部件；保护表单免受机器人攻击。 | | **Capture Credentials** | 从表单提交中捕获凭据；将其存储在上下文和数据库中以供下游插件使用。 | | **Conditional Logic** | 利用上下文（相等性、包含、数值、正则表达式）在 True/False 上分支工作流。 | | **Data Transform** | 为下游插件设置、移除、复制、重命名、合并或过滤上下文数据。 | | **Delay** | 固定或随机延迟，或延迟至特定日期时间；用于速率限制和时间控制。 | | **Email Template Validator** | 验证模板（Jinja2、质量、垃圾邮件）；可选的 AI 支持；根据结果进行分支。 | | **Generate Device Code (GraphSpy)** | 通过 GraphSpy API 生成 Azure AD 设备代码；与 AWS Connect 结合使用以进行语音投递。 | | **AWS Connect Dialer** | 通过 Connect 进行出站语音；支持 SSML；与 GraphSpy 集成用于设备代码。 | | **Log Event** | 将自定义事件记录到数据库；记录请求/会话数据；用于审计和分析。 | | **Phishing Detector (BERT)** | 基于 ML 的 HTML 钓鱼检测；QA 和内容分析。 | | **Pushover** | 通过 Pushover API 推送通知（iOS、Android、桌面端）。 | | **Queue Credential Proxy** | 在 Capture Credentials 之后，排队一个浏览器自动化任务以在目标站点上重放。 | | **Redirect** | 带有可配置状态码的 HTTP 重定向；支持变量插值。 | | **Render Template** | 使用 Jinja2 和变量，从活动、自定义或库模板渲染 HTML。 | | **Send Slack Message** | 通过 webhook 或机器人向 Slack 发送消息；支持变量插值。 | | **SMTP Email Sender** | 通过 SMTP 发送电子邮件（TLS、身份验证、HTML/纯文本、变量）；用于发送工作流。 | | **Target Selector** | 从 CSV、手动列表或被追踪的用户中选择目标；按域名/数量过滤；为发送工作流提供数据。 | | **URL Obfuscator** | 混淆 IP/URL（例如 DWORD、十六进制、IPv6 映射）；用于测试和研究。 | | **User Agent Check** | 根据 user-agent 正则表达式允许或阻止；根据结果阻止、重定向或分支。 | | **Validate Input** | 验证表单字段（必填、类型、长度、正则表达式）；根据结果阻止、重定向或继续执行。 | ## 开发 - 运行测试：`make test-fast` 或 `./run_tests.sh` - 带有覆盖率的测试：`make test-coverage` 或 `./run_tests.sh --coverage` - Lint：`make lint` - 格式检查：`make format-check` 请参阅 [Makefile](Makefile) 获取更多目标（单元/集成/功能测试拆分，数据库初始化/重置，仅运行管理或钓鱼服务器）。 ## 文档 - [DEVELOPMENT.md](DEVELOPMENT.md) — 开发自定义插件的详细说明。 - [AGENT_README.md](AGENT_README.md) — 面向 AI 智能体：代码库概念、插件系统、风格指南和提示词。

标签：Flask, Python, Web应用开发, 凭据扫描, 无后门, 特征检测, 系统调用监控, 请求拦截, 逆向工具