syed-sameer-ul-hassan/MailSpoof

**MailSpoof** 是一个专业的开源电子邮件伪造和网络钓鱼模拟框架，专为授权的渗透测试、红队演练和安全意识培训而设计。它使用 Python 构建，具有内置的 SMTP 测试服务器、预置的攻击场景、自定义模板创建、审计日志记录和报告生成功能。 ## 目录 - [功能](#features) - [技术栈](#technology-stack) - [工作原理](#how-it-works) - [快速开始](#quick-start) - [安装](#installation) - [用法](#usage) - [交互式会话工作流](#interactive-session-workflow) - [模板生命周期](#template-lifecycle) - [SMTP 配置文件工作流](#smtp-profile-workflow) - [报告生成流程](#report-generation-flow) - [电子邮件伪造场景](#email-spoofing-scenarios) - [自定义模板](#custom-templates) - [SMTP 中继与发送](#smtp-relay--delivery) - [审计日志与报告](#audit-logs--reports) - [项目结构](#project-structure) - [疑难解答](#troubleshooting) - [许可证](#license) - [法律声明](#legal-notice) ## 功能 - **内置 SMTP 服务器** — 具有可选 MX 中继功能的多线程原始 socket SMTP 服务器，用于本地测试 - **HTTP 追踪服务器** — 在 8080 端口内置 HTTP 服务器，用于对已发送邮件进行打开/像素追踪 - **62 个网络钓鱼模板** — 包含 62 个预置的 HTML 邮件模板，涵盖社交媒体、SaaS、金融、物流、开发者平台和 BEC - **自定义模板引擎** — 以交互方式创建、编辑、预览、过滤和删除您自己的网络钓鱼邮件模板 - **外部 SMTP 中继** — 支持通过 Gmail、Outlook、SendGrid 或任何支持 TLS/SSL 的已验证 SMTP 服务器进行发送 - **SMTP 配置文件管理** — 保存并重复使用命名的 SMTP 中继配置 - **批量目标列表** — 通过单个命令使用 `--target-list targets.csv` 向数百个目标发送邮件 - **附件载荷** — 通过 `--attach` 将文件（PDF、DOCX 等）附加到电子邮件中，以测试网关过滤 - **高级标头** — 注入自定义的 `--reply-to` 和 `--x-mailer` 标头，用于高级绕过测试 - **审计日志** — 每次测试都会记录时间戳、成功/失败状态、错误详情和服务器详情 - **JSON 与 CSV 报告** — 生成包含成功率、单次测试错误和安全建议的评估报告 - **模板预览** — 在发送前预览 HTML/文本内容 - **模板过滤** — 按名称、类别、标签或内容过滤模板 - **Docker 支持** — 使用 `docker-compose up` 在任意 VPS 上即时部署 - **桌面启动器** — 带有图标的 `.desktop` 条目，适用于 Linux 应用程序菜单（自动安装） - **跨平台** — 适用于 Linux、macOS 和 Termux (Android) - **Apache-2.0 授权** — 可免费用于商业和个人用途 ### 架构概述 ``` flowchart TD A[User] -->|CLI| B[mailspoof] B --> C[lib/cli.py] C --> D{Command?} D -->|start / server| E[lib/server.py
SMTP Server] D -->|test / custom| F[lib/engine.py
Email Builder] D -->|list / create / preview / edit / remove| G[lib/core.py
Templates] D -->|logs / report| H[lib/audit.py
Audit & Reports] D -->|profile| I[lib/core.py
Config & Profiles] E -->|MX Relay| M[Recipient Mail Server] F -->|Send| J[External SMTP Relay] F -->|Send| E J --> M H --> K[audit.log / reports/] ``` ## 技术栈 MailSpoof 完全使用 **Python 3.8+** 构建，核心功能无需任何外部运行时依赖。以下是完整的技术细分： ### 核心语言与标准库 | 技术 | 用途 | |------------|---------| | **Python 3.8+** | 带有类型提示的核心编程语言 (`\|`, `list[T]`) | | **argparse** | CLI 参数解析和子命令路由 (`start`, `test`, `custom`, `list`, `create`, `preview`, `edit-template`, `remove-template`, `profile`, `logs`, `report`) | | **smtplib** | 用于外部中继发送的 SMTP 客户端 (AUTH, STARTTLS, SSL) | | **socket** | 用于内置 SMTP 服务器的原始 TCP socket 处理 | | **threading** | 多线程内置 SMTP 服务器（并发客户端会话） | | **json** | 配置文件 (`config.json`) 和审计日志 (`audit.log`) 序列化 | | **logging** | 结构化的审计日志记录到文件和标准输出 | ### 电子邮件与 MIME 构造 | 技术 | 用途 | |------------|---------| | **email.mime.multipart** | `multipart/alternative` MIME 消息 (HTML + 纯文本) | | **email.mime.text** | 用于电子邮件正文的 MIME 文本部分 | | **email.header** | UTF-8 编码的电子邮件主题标头 | | **email.utils** | Message-ID 生成和符合 RFC 的日期格式化 | | **html** | HTML 到文本的转换，用于纯文本回退 | ### 数据与配置 | 技术 | 用途 | |------------|---------| | **dataclasses** | `Scenario`, `TestResult` 类型化数据结构 | | **pathlib** | 跨平台路径处理 (`~/.mailspoof/`, 模板) | | **re** | 用于 HTML 剥离、模板解析、SMTP 响应解析的正则表达式 | ### 可选依赖项 | 技术 | 用途 | |------------|---------| | **dnspython** | 用于直接 MX 发送的 DNS MX 记录查找 (`pip install dnspython`) | | **setuptools** | 包构建和控制台脚本入口点 | | **wheel** | Python wheel 分发格式 | ### 报告与输出 | 技术 | 用途 | |------------|---------| | **JSON** | 默认报告格式 (`report_YYYYMMDD_HHMMSS.json`) | | **CSV** | 表格报告导出 (`report_YYYYMMDD_HHMMSS.csv`) | | **ANSI 颜色代码** | 终端彩色输出（红/黄/绿/青色代表严重程度） | ### 打包与分发 | 技术 | 用途 | |------------|---------| | **setuptools + setup.py** | 兼容 PyPI 的包，带有控制台脚本入口点 | | **pyproject.toml** | 现代 Python 打包 (PEP 517/518) | | **.deb / dpkg** | Debian/Ubuntu 系统包 | | **.rpm / rpmbuild** | Fedora/RHEL/CentOS 系统包 | | **PKGBUILD** | Arch Linux AUR 包 | | **Makefile** | 通用的安装/卸载 | ### 桌面集成 | 技术 | 用途 | |------------|---------| | **.desktop entry** | Linux 应用程序菜单启动器 | | **SVG icon** | 适用于所有显示分辨率的可缩放矢量图标 | | **XDG directories** | 标准图标/应用程序路径 (`~/.local/share/`, `/usr/share/`) | ## 工作原理 MailSpoof 通过简单的 3 阶段流水线运行：**选择**模板，**配置**目标和 SMTP 中继，然后**发送**并记录结果。 ``` flowchart LR A[Select Template] --> B[Configure Target & SMTP] B --> C[Build HTML Email] C --> D[Send via Relay or MX] D --> E{Success?} E -->|Yes| F[Log Success + Report] E -->|No| G[Log Error + Tips] F --> H[Audit.log] G --> H ``` **关键路径：** - **内置模板** → 45+ 个即用型场景 - **自定义模板** → 使用 `mailspoof create` 创建您自己的模板 - **SMTP 中继** → 使用 Gmail、Outlook、SendGrid 或已保存的配置文件 - **直接 MX** → 直接发送到收件人服务器（通常会被 ISP 阻止） ## 快速开始 ``` git clone https://github.com/syed-sameer-ul-hassan/MailSpoof.git cd MailSpoof pip install -r requirements.txt chmod +x mailspoof ./mailspoof --version ``` 或者通过 Debian 包安装： ``` sudo dpkg -i mailspoof-v1.2.0.deb mailspoof --version ``` ## 安装说明 ### 选项 1：通用安装程序（任何发行版） 自动检测您的平台并安装依赖项： ``` bash install.sh ``` 支持：**Debian/Ubuntu**、**Fedora/RHEL/CentOS**、**Arch/Manjaro**、**macOS**、**Termux** 等。 ### 选项 2：Debian / Ubuntu (.deb) ``` sudo dpkg -i mailspoof-v1.2.0.deb sudo apt-get install -f ``` 或者从源码构建： ``` bash scripts/build-deb.sh ``` ### 选项 3：Fedora / RHEL / CentOS (.rpm) ``` sudo dnf install rpm-build rpmbuild -ba mailspoof.spec sudo rpm -i ~/rpmbuild/RPMS/noarch/mailspoof-*.rpm ``` ### 选项 4：Arch Linux (AUR / PKGBUILD) ``` makepkg -si ``` 或手动安装： ``` cd /tmp git clone https://aur.archlinux.org/mailspoof.git cd mailspoof makepkg -si ``` ### 选项 5：通用 Makefile ``` make install sudo make install PREFIX=/usr ``` ### 选项 6：手动 / 开发 ``` python3 -m venv venv source venv/bin/activate pip install -r requirements.txt ./mailspoof list ``` **要求：** Python 3.8+，`python3-venv`（或在基于 RPM 的发行版上为 `python3-virtualenv`） ## 用法 ### 交互式会话工作流 ``` flowchart TD A[mailspoof start] --> B[Start SMTP Server
port 2525] B --> C[Select Template ID] C --> D[Enter Target Email] D --> E[Enter Spoofed From
ceo@company.com] E --> F[Enter Subject] F --> G{Use External Relay?} G -->|Yes| H[Enter SMTP Host
User / Pass / TLS] G -->|No| I[Direct MX Delivery] H --> J[Confirm & Send] I --> J J --> K{Delivery Result} K -->|Success| L[Log to audit.log] K -->|Failed| M[Show Error + Tips] M --> N[Retry with Relay] ``` ### 交互式电子邮件伪造会话 启动内置 SMTP 服务器并以交互方式发送伪造的电子邮件： ``` mailspoof start --port 2525 ``` 系统将提示您输入： - 目标电子邮件地址 - 伪造的发件人电子邮件地址及显示名称 - 主题行 - 外部 SMTP 中继设置（可选，推荐） - 模板 ID ### 运行内置网络钓鱼场景 ``` mailspoof test 1 victim@company.com ``` ### 仅启动 SMTP 服务器 ``` mailspoof server --host 0.0.0.0 --port 2525 ``` ### 列出所有模板 ``` mailspoof list # All templates mailspoof list --filter linkedin # Filter by name/tag/content mailspoof list --filter "social media" # Filter by category ``` ### 创建自定义网络钓鱼模板 ``` mailspoof create # 或 mailspoof -t ``` 自定义模板会自动分配下一个可用的 ID。 ### 预览模板 ``` mailspoof preview 1 # Text preview (strips HTML) mailspoof preview 1 --raw # Show raw HTML ``` ### 编辑模板 ``` mailspoof edit-template 1 # Edit in $EDITOR (default nano) ``` 适用于内置和自定义模板。 ### 删除模板 ``` mailspoof remove-template 46 # Only custom templates ``` ### 模板生命周期 管理从创建到删除的模板： ``` flowchart TD A[mailspoof create] --> B[Auto-assign ID] B --> C[Save to ~/.mailspoof/templates/custom/] C --> D[mailspoof list] D --> E{Need changes?} E -->|Yes| F[mailspoof edit-template ] F --> G[Edit in $EDITOR] G --> D E -->|No| H[mailspoof preview ] H --> I[mailspoof test target@email.com] I --> J{Done with template?} J -->|Yes| K[mailspoof remove-template ] J -->|No| D ``` ### 完全自定义的邮件测试 ``` mailspoof custom \ --from-email "ceo@company.com" \ --from-name "CEO" \ --subject "Urgent: Wire Transfer Required" \ --body "Please review the attached invoice." \ --target "finance@company.com" \ --smtp-host smtp.gmail.com \ --smtp-port 587 \ --smtp-user your.email@gmail.com \ --smtp-pass YOUR_APP_PASSWORD \ --use-tls \ --verbose ``` ### 批量目标列表 (CSV) ``` # targets.csv: 每行一个邮箱 mailspoof test 1 --target-list employees.csv --smtp-host smtp.gmail.com --smtp-port 587 --smtp-user user@gmail.com --smtp-pass APP_PASS --use-tls ``` ### 带有附件的电子邮件 ``` # 附加一个或多个文件以测试 gateway 过滤 mailspoof test 7 target@company.com --attach report.pdf --attach policy.docx ``` ### 高级标头注入 ``` mailspoof custom --from-email ceo@company.com --from-name CEO \ --subject "Urgent" --body "See attached" \ --target finance@company.com \ --reply-to attacker@evil.com \ --x-mailer "Microsoft Outlook 16.0" ``` ### 使用已保存的 SMTP 配置文件 ``` # 保存 profile mailspoof profile add gmail --host smtp.gmail.com --port 587 --user your.email@gmail.com --pass APP_PASSWORD --use-tls # 列出 profiles mailspoof profile list # 在任何命令中使用 profile mailspoof test 1 victim@company.com --profile gmail --verbose mailspoof custom --from-email ... --target ... --profile gmail mailspoof start --profile gmail ``` ### SMTP 配置文件工作流 保存一次凭据，即可在所有发送命令中重复使用： ``` flowchart LR A[mailspoof profile add ] --> B[Store in ~/.mailspoof/config.json] B --> C[mailspoof profile list] C --> D[mailspoof test 1 target --profile ] D --> E[Auto-fill host/port/user/pass] E --> F[Send Email] F --> G[mailspoof profile remove ] ``` ### 查看审计日志 ``` mailspoof logs --lines 50 ``` ### 生成安全评估报告 ``` mailspoof report # JSON (default) mailspoof report --format csv # CSV format mailspoof report --output ./report.csv --format csv ``` ### 报告生成流程 每次发送都会被记录。报告会将这些汇总为可操作的评估： ``` flowchart TD A[mailspoof test 1 target] --> B[Log to ~/.mailspoof/audit.log] C[mailspoof custom ...] --> B D[mailspoof start ...] --> B B --> E[mailspoof report] E --> F{Format?} F -->|json| G[report_YYYYMMDD_HHMMSS.json] F -->|csv| H[report_YYYYMMDD_HHMMSS.csv] G --> I[Success rate, risk level, per-test errors] H --> I ``` ## 电子邮件伪造场景 MailSpoof 包含 **62 个专业制作的** HTML 网络钓鱼模拟模板，涵盖多个类别： | ID | 场景 | 类别 | 严重程度 | |----|----------|----------|----------| | 1 | 付款授权 - CFO | BEC | 严重 | | 2 | IT 服务台 - 密码重置 | 凭据收集 | 高 | | 3 | 账户暂停通知 - 银行安全 | 金融 | 严重 | | 4 | Microsoft 365 许可证过期通知 | SaaS | 中 | | 5 | PayPal 账户审查 | 金融 | 高 | | 6 | HR 福利表格更新 | HR | 高 | | 9 | LinkedIn 安全验证 | 社交媒体 | 高 | | 12 | Twitter/X 账户锁定通知 | 社交媒体 | 高 | | 17 | GitHub OAuth 重新认证 | 开发者 | 高 | | 20 | AWS 根访问警报 | 云计算 | 严重 | | 46 | IT 帮助台 - 密码过期 | 凭据收集 | 高 | | 47 | HR - 政策更新（附件） | 附件测试 | 中 | | 48 | Microsoft 365 - 异常活动 | 凭据收集 | 高 | | 49 | DHL - 包裹递送失败 | 物流钓鱼 | 中 | | 50 | FedEx - 包裹滞留 | 物流钓鱼 | 中 | | 51 | Apple ID - 账户已暂停 | 凭据收集 | 高 | | 52 | Google - 严重安全警报 | 凭据收集 | 高 | | 53 | Amazon - 账户已锁定 | 凭据收集 | 高 | | 54 | 企业 VPN - 证书已过期 | IT 基础设施 | 高 | | 55 | DocuSign - 签名请求 | 文档钓鱼 | 中 | | 56 | SharePoint - 与您共享的文件 | 文档钓鱼 | 中| 57 | Zoom - 会议邀请 | 通讯平台 | 低 | | 58 | Coinbase - 可疑提款 | 金融钓鱼 | 严重 | | 59 | Office 365 - 邮箱配额已超 | 凭据收集 | 中 | | 60 | Wise - 电汇确认 | 金融钓鱼 | 严重 | | 61 | GitHub - 已添加 SSH 密钥 | 开发者平台 | 高 | | 62 | 新设备登录警报 | 设备警报 | 高 | **完整目录：** 查看 [docs/SECURITY_SCENARIOS.md](docs/SECURITY_SCENARIOS.md) 获取全部 62 个模板。 ## 自定义模板 通过将 `.txt` 文件拖入以下目录来创建您自己的电子邮件伪造场景： ``` ~/.mailspoof/templates/ ``` ### 简单的纯正文模板 ``` Dear user, Your account has been compromised. Click the link below to reset. https://evil.com/reset ``` ### 带有元数据的完整模板 ``` Id: 47 Name: Custom Phishing Test Category: Social Engineering Severity: High From Email: security@company.com From Name: Security Team Subject: Immediate Action Required Body:

Your message here.

Action Description: Tests employee awareness of suspicious links. Tags: custom, testing ``` **字段：** - `Id` — 唯一 ID（通过 `mailspoof create` 创建的自定义模板会自动分配） - `Name` — 模板显示名称 - `Category` — 模板类别（例如，Custom、Social Media、Financial） - `Severity` — Critical / High / Medium / Low - `From Email` — 默认发件人电子邮件地址 - `From Name` — 默认发件人显示名称 - `Subject` — 默认电子邮件主题 - `Body` — 电子邮件正文（支持 HTML；`{TODAY}` 将替换为当前日期） - `Description` — 模板描述 - `Tags` — 以逗号分隔的用于过滤的标签（例如，`social, saas`） ## SMTP 中继与发送 来自住宅 IP 的直接 MX 发送会被 Gmail、Yahoo 和 Outlook 阻止。MailSpoof 会检测到这一点并建议使用外部 SMTP 中继。 **推荐的 relay：** - **Gmail** — `smtp.gmail.com:587`（使用应用密码） - **Outlook** — `smtp.office365.com:587` - **SendGrid** — `smtp.sendgrid.net:587` - **Custom** — 任何已验证的 SMTP 服务器 请参阅 [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) 了解发送错误修复方法。 ## 审计日志与报告 所有电子邮件伪造测试都会自动记录： - **日志文件：** `~/.mailspoof/audit.log` - **JSON 报告：** `~/.mailspoof/reports/report_YYYYMMDD_HHMMSS.json` - **CSV 报告：** `~/.mailspoof/reports/report_YYYYMMDD_HHMMSS.csv` 报告包含： - 测试总数、成功/失败计数 - 成功率百分比 - 单次测试的错误详情 - 风险评估（CRITICAL / HIGH / MEDIUM） - SPF/DKIM/DMARC 绕过建议 - 按场景和测试类型细分 ## 项目结构 ``` MailSpoof/ ├── lib/ │ ├── banner.py # Shared logo / banner helpers │ ├── core.py # Configuration, data classes, scenarios, profiles │ ├── server.py # Multi-threaded SMTP + HTTP tracking server (port 8080) │ ├── engine.py # Email crafting, attachments, delivery, error handling │ ├── audit.py # Log viewer and report generator (JSON/CSV) │ └── cli.py # Command-line interface ├── lib/templates/ │ └── builtins/ # 62 pre-built HTML phishing scenarios ├── assets/ │ └── icon.svg # Application icon for desktop launcher ├── docs/ │ ├── SECURITY_SCENARIOS.md # Full 62 template catalog │ ├── TROUBLESHOOTING.md # Delivery error fixes │ ├── DEPLOYMENT.md # Deployment guide │ └── CHANGELOG.md # Version history & release notes ├── scripts/ │ ├── build-deb.sh # Debian package builder │ └── mailspoof-wrapper.sh # System wrapper script ├── .github/ │ ├── ISSUE_TEMPLATE/ # Bug/feature templates │ ├── FUNDING.yml # Sponsorship links │ └── dependabot.yml # Dependency updates ├── Dockerfile # Docker container definition ├── docker-compose.yml # Docker compose config ├── mailspoof # Entry-point executable ├── mailspoof.desktop # Linux desktop launcher (auto-installed) ├── install.sh # Universal cross-platform installer (Linux/macOS/Termux) ├── install_termux.sh # Dedicated Termux installer ├── uninstall.py # Python uninstaller ├── setup.py # PyPI setuptools config ├── pyproject.toml # Modern Python packaging ├── requirements.txt # Python dependencies ├── PKGBUILD # Arch Linux package build ├── mailspoof.spec # Fedora/RHEL RPM spec ├── Makefile # Generic build & install ├── SECURITY.md # Security policy & responsible use ├── CITATION.cff # Citation metadata ├── CODE_OF_CONDUCT.md # Community guidelines ├── CONTRIBUTING.md # Contribution guidelines ├── .gitignore # Git ignore rules ├── LICENSE # Apache-2.0 └── README.md # This file ``` ## 疑难解答 常见问题和修复方法记录在 [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) 中，包括： - IP 黑名单错误 (TSS09, 550, 553) - 端口 25 连接失败 - SMTP 身份验证问题 - Gmail 应用密码设置 - Debian 软件包安装 ## 高级配置 ### 环境变量 | 变量 | 描述 | 默认值 | |----------|-------------|---------| | `MAILSPOOF_CONFIG_DIR` | 配置目录路径 | `~/.mailspoof` | | `MAILSPOOF_LOG_LEVEL` | 日志级别 (DEBUG, INFO, WARNING) | INFO | | `MAILSPOOF_SMTP_HOST` | 默认 SMTP 中继主机 | localhost | | `MAILSPOOF_SMTP_PORT` | 默认 SMTP 中继端口 | 2525 | ### 自定义配置文件 编辑 `~/.mailspoof/config.json` 以设置默认值： ``` { "default_smtp_host": "smtp.gmail.com", "default_smtp_port": 587, "default_use_tls": true, "log_level": "INFO", "max_retries": 3, "timeout": 30 } ``` ## 模板格式规范 MailSpoof 模板是具有简单键值格式的纯文本文件。 ### 完整模板语法 ``` Name: Template Name Category: Attack Category Severity: Low | Medium | High | Critical From Email: spoofed@sender.com From Name: Spoofed Display Name Subject: Email Subject Line Body: This is the email body. It supports multiple lines. HTML tags are NOT supported. Description: Brief description of what this scenario tests. ``` ### 纯正文模板语法 对于简单的模板，只需要正文文本： ``` Hello {{target_name}}, Your account requires verification. Please click: https://example.com/verify Regards, Security Team ``` 像 `{{target_name}}` 这样的占位符不会被 MailSpoof 处理。它们会按原样包含在电子邮件正文中。请使用自定义模板进行针对目标的个性化设置。 ### 模板存储位置 ``` ~/.mailspoof/templates/ # User custom templates /usr/share/mailspoof/templates/builtins/ # Built-in templates ``` ## 电子邮件标头剖析 当 MailSpoof 发送电子邮件时，会构造以下标头： ``` From: Spoofed Name To: Target User Subject: Urgent Action Required Date: Mon, 04 Jun 2026 12:00:00 +0000 Message-ID: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: 7bit ``` ### 标头注入预防 MailSpoof 会自动清理输入，以防止标头注入攻击： - 去除 `From`、`To`、`Subject` 中的换行符 - 移除控制字符 - 最大主题长度：998 个字符 (RFC 5322) ## SMTP 服务器内部机制 内置的 SMTP 服务器 (`lib/server.py`) 实现了一个最小化的、兼容 RFC 5321 的服务器： ### 支持的命令 | 命令 | 描述 | |---------|-------------| | `HELO` / `EHLO` | 客户端问候 | | `MAIL FROM` | 发件人地址 | | `RCPT TO` | 收件人地址 | | `DATA` | 电子邮件正文 | | `RSET` | 重置事务 | | `QUIT` | 关闭连接 | ### MX 中继过程 ``` sequenceDiagram participant Client as Email Client participant MS as MailSpoof SMTP participant DNS as DNS Resolver participant MX as MX Server Client->>MS: EHLO example.com MS-->>Client: 250 Hello Client->>MS: MAIL FROM: MS-->>Client: 250 OK Client->>MS: RCPT TO: MS-->>Client: 250 OK Client->>MS: DATA MS-->>Client: 354 End data with . Client->>MS: Email body... MS->>DNS: Query MX for target.com DNS-->>MX: MX records MS->>MX: SMTP relay MX-->>MS: 250 OK / 550 Error MS-->>Client: 250 Queued / 550 Failed ``` ### 端口绑定 ``` mailspoof server --host 0.0.0.0 --port 2525 ``` - **端口 2525**：无需 root 权限，推荐用于测试 - **端口 25**：需要 root 权限，用于直接 MX 中继 - **端口 587**：用于 STARTTLS 外部中继提交 ## 安全注意事项 ### 负责任的使用 1. **在测试前始终获得书面授权** 2. **在正式的委托书中记录测试范围** 3. **为评估窗口设定时间限制** 4. **在测试前后通知利益相关者** 5. **通过审计日志保留证据** ### IP 信誉 来自住宅 IP 的直接 MX 发送会受到严格的过滤： | 提供商 | 过滤类型 | 成功率 | |----------|-------------|--------------| | Gmail | IP 信誉 + SPF/DKIM/DMARC | 极低 | | Yahoo | IP 黑名单 (TSS09) | 极低 | | Outlook | IP 信誉 + 发件人评分 | 极低 | | 自定义 | 取决于配置 | 可变 | ### 使用外部中继 外部 SMTP 中继可以绕过 IP 信誉检查，因为它们使用了成熟的邮件服务器基础设施。 ## 速率限制与道德规范 ### 内置速率限制 MailSpoof 不强制执行速率限制。作为操作者，您必须自行实施： ``` # 示例：限制为每分钟 10 封邮件 for i in {1..10}; do mailspoof test 1 "target$i@example.com" --smtp-host smtp.gmail.com sleep 6 done ``` ### 道德准则 - 不要发送给随机地址 - 不要用于垃圾邮件或骚扰 - 不要伪造政府或执法部门域名 - 立即尊重退订请求 - 对日志保密并加密 ## Windows / WSL 设置 ## 适用于 Linux 的 Windows 子系统 (WSL2) ``` # 在 PowerShell (Admin) 中 wsl --install -d Ubuntu # 重启，然后打开 Ubuntu 终端 cd ~ git clone https://github.com/syed-sameer-ul-hassan/MailSpoof.git cd MailSpoof bash install.sh ``` ### 原生 Windows（不推荐） MailSpoof 专为类 Unix 系统设计。对于原生 Windows： 1. 从 python.org 安装 Python 3.8+ 2. 安装 Git for Windows 3. 使用 Git Bash 或 PowerShell 4. 运行 `python mailspoof` 而不是 `./mailspoof` ## Docker 部署 MailSpoof 包含了一个可即用型 `Dockerfile` 和 `docker-compose.yml`，用于在任何 VPS 上部署： ``` # 构建并启动 SMTP + Tracking 服务器 docker-compose up -d ``` 这会将 `~/.mailspoof` 挂载为卷，以便所有配置和模板持久化保存。 ``` # 或手动构建并运行 docker build -t mailspoof . docker run -it --rm --network=host mailspoof server --port 2525 ``` ## 云部署 ### AWS EC2 ``` # 启动 Ubuntu 22.04 实例 sudo apt update && sudo apt install -y python3 python3-venv git git clone https://github.com/syed-sameer-ul-hassan/MailSpoof.git cd MailSpoof bash install.sh # 在 Security Group 中开放端口 2525 ``` ### Google Cloud Platform ``` # 创建允许 SMTP 出站的 VM gcloud compute instances create mailspoof-test \ --image-family=ubuntu-2204-lts \ --image-project=ubuntu-os-cloud # SSH 并按上述步骤安装 ``` ### Azure VM ``` # 标准 Ubuntu VM # 在 NSG 中允许出站端口 587 bash install.sh ``` ## CI/CD 集成 ### GitHub Actions 示例 ``` jobs: email-test: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - run: pip install -r requirements.txt - run: ./mailspoof test 1 test@example.com --smtp-host ${{ secrets.SMTP_HOST }} ``` ### GitLab CI 示例 ``` test_email: image: python:3.11 script: - pip install -r requirements.txt - ./mailspoof test 1 $TEST_EMAIL --smtp-host $SMTP_HOST ``` ## 编程式 API 用法 虽然 MailSpoof 主要是一个 CLI 工具，但您可以直接使用其函数： ``` from lib.core import Config, Scenario from lib.engine import send_email, run_scenario config = Config() scenario = Scenario( id=1, name="CEO Fraud", category="BEC", severity="Critical", from_email="ceo@company.com", from_name="CEO", subject="Urgent: Wire Transfer", body="Please process the attached transfer.", description="CEO fraud simulation", source="custom", ) ok = run_scenario( scenario, "target@company.com", "smtp.gmail.com", 587, config, smtp_user="user@gmail.com", smtp_pass="app_password", use_tls=True, ) print("Sent!" if ok else "Failed") ``` ## 自定义插件开发 MailSpoof 没有正式的插件 API，但您可以通过以下方式进行扩展： 1. 将模板文件添加到 `templates/builtins/` 2. 修改 `lib/core.py` 以注册新场景 3. 扩展 `lib/engine.py` 以实现自定义发送逻辑 ### 以编程方式添加新场景 ``` from lib.core import Scenario my_scenario = Scenario( id=99, name="Custom Test", category="Social Engineering", severity="Medium", from_email="support@fake-service.com", from_name="Support Team", subject="Account Verification Required", body="Please verify your account at https://fake-link.com", description="Custom awareness test", source="custom", ) ``` ## 性能调优 ### 并发测试 MailSpoof 的 SMTP 服务器通过线程处理并发连接： ``` # 默认：每个客户端 1 个连接 # 服务器支持多个同时连接的客户端 mailspoof server --port 2525 ``` ### 内存使用情况 | 组件 | 内存 | |-----------|--------| | CLI 启动 | ~20 MB | | SMTP 服务器 | ~30 MB | | 每封邮件 | ~5 MB | | 完整审计日志 | 随条目增加 | ### 磁盘使用情况 ``` # 检查日志大小 ls -lh ~/.mailspoof/audit.log # 轮转日志 mv ~/.mailspoof/audit.log ~/.mailspoof/audit.log.$(date +%Y%m%d) ``` ## 日志配置 ### 默认日志格式 ``` {"timestamp": "2026-06-04T12:00:00", "scenario_id": 1, "target": "user@company.com", "success": true, "server": "smtp.gmail.com:587"} ``` ### 日志轮换 MailSpoof 不会自动轮换日志。请使用 `logrotate`： ``` # /etc/logrotate.d/mailspoof /home/*/.mailspoof/audit.log { daily rotate 7 compress delaycompress missingok notifempty } ``` ## 报告 Schema ### JSON 报告结构 ``` { "generated_at": "2026-06-04T12:00:00", "total_tests": 10, "successful": 7, "failed": 3, "success_rate": 70.0, "risk_level": "HIGH", "recommendations": [ "Implement SPF record", "Enable DMARC enforcement", "Train employees on phishing" ], "entries": [ { "timestamp": "2026-06-04T11:00:00", "scenario": "CEO Fraud", "target": "finance@company.com", "success": true } ] } ``` ## 与其他工具的比较 | 功能 | MailSpoof | Gophish | Social-Engineer Toolkit | |---------|-----------|---------|------------------------| | 内置 SMTP | 是 | 是 | 否 | | HTTP 追踪服务器 | 是 | 是 | 否 | | 批量 CSV 目标 | 是 | 是 | 否 | | 电子邮件附件 | 是 | 否 | 否 | | Docker 支持 | 是 | 是 | 否 | | 自定义模板 | 是 | 是 | 是 | | Web 仪表板 | 否 | 是 | 否 | | 开源 | 是 | 是 | 是 | | CLI 优先 | 是 | 否 | 是 | | Debian 软件包 | 是 | 否 | 否 | | 跨平台 | 是 | 是 | 仅限 Linux | | 轻量级 | 是 | 中等 | 重量级 | MailSpoof 专为喜欢轻量级、可编写脚本且没有 Web 仪表板开销的 CLI 工具的用户而设计。 ## 常见问题 ### 问：我可以发送到 Gmail 吗？ 可以，但请使用外部 SMTP 中继。从住宅 IP 直接进行 MX 发送到 Gmail 会失败。 ### 问：这违法吗？ MailSpoof 用于授权的安全测试时是合法的。未经授权的使用在大多数司法管辖区都违反了计算机欺诈法。 ### 问：它支持 HTML 邮件吗？ 是的！MailSpoof 会自动构建 `text/plain` 和 `text/html` 多部分邮件。所有 62 个内置模板都是带有完整样式的 HTML 电子邮件。 ### 问：我可以安排活动吗？ 使用 `cron` 进行计划测试： ``` crontab -e # 每周一上午 9 点运行测试 0 9 * * 1 /usr/bin/mailspoof test 1 target@company.com --smtp-host smtp.gmail.com --smtp-port 587 ``` ### 问：如何更新？ ``` cd MailSpoof git pull bash install.sh ``` 或通过 `.deb`： ``` sudo dpkg -i mailspoof-v1.2.0.deb ``` ### 问：模板存储在哪里？ 内置：`/usr/share/mailspoof/templates/builtins/`（系统）或项目目录（手动） 自定义：`~/.mailspoof/templates/` ### 问：可以在 VPS 上使用吗？ 可以。大多数云提供商默认阻止端口 25。请申请解封端口 25 或使用端口 587 上的外部 SMTP 中继。 ### 问：需要什么 Python 版本？ Python 3.8 或更高版本。已在 3.8、3.9、3.10、3.11、3.12、3.13 上进行测试。 ### 问：可以离线工作吗？ SMTP 服务器可以离线工作。电子邮件发送需要互联网连接。 ### 问：可以链式执行命令吗？ 可以，请使用 shell 脚本： ``` mailspoof test 1 user1@company.com && \ mailspoof test 2 user2@company.com && \ mailspoof report --output report.json ``` ## 术语表 | 术语 | 定义 | |------|------------| | **BEC** | 商业电子邮件妥协 | | **DMARC** | 基于域的消息身份验证、报告和一致性 | | **DKIM** | 域密钥识别邮件 | | **MX** | 邮件交换（用于邮件服务器的 DNS 记录） | | **PHI** | 受保护的健康信息 | | **PII** | 个人身份信息 | | **RBL** | 实时黑洞列表 | | **SPF** | 发件人策略框架 | | **STARTTLS** | 将纯文本连接升级为 TLS | | **TSS09** | Yahoo 特定的 IP 黑名单错误代码 | ## 高级 SMTP 中继设置 ### Gmail / Google Workspace ``` mailspoof test 1 target@gmail.com \ --smtp-host smtp.gmail.com \ --smtp-port 587 \ --smtp-user your.email@gmail.com \ --smtp-pass "xxxx xxxx xxxx xxxx" \ --use-tls ``` 在以下地址生成应用密码：https://myaccount.google.com/apppasswords ### Microsoft 365 / Outlook ``` mailspoof test 1 target@outlook.com \ --smtp-host smtp.office365.com \ --smtp-port 587 \ --smtp-user your.email@company.com \ --smtp-pass YOUR_PASSWORD \ --use-tls ``` ### SendGrid ``` mailspoof test 1 target@company.com \ --smtp-host smtp.sendgrid.net \ --smtp-port 587 \ --smtp-user apikey \ --smtp-pass YOUR_SENDGRID_API_KEY \ --use-tls ``` ### Amazon SES ``` mailspoof test 1 target@company.com \ --smtp-host email-smtp.us-east-1.amazonaws.com \ --smtp-port 587 \ --smtp-user YOUR_SES_USERNAME \ --smtp-pass YOUR_SES_PASSWORD \ --use-tls ``` ### 自定义 SMTP 服务器 ``` mailspoof test 1 target@company.com \ --smtp-host mail.yourserver.com \ --smtp-port 25 \ --smtp-user admin \ --smtp-pass password ``` ## 开发设置 ### 运行测试 ``` python3 -m py_compile lib/*.py mailspoof uninstall.py bash -n install.sh ``` ### 代码检查 ``` pip install ruff ruff check . --ignore E501 ``` ### 类型检查 ``` pip install pyright pyright lib/ mailspoof uninstall.py ``` ### 构建软件包 ``` # Debian bash scripts/build-deb.sh # RPM rpmbuild -ba mailspoof.spec # Arch makepkg -si ``` ## 调试 启用详细日志记录： ``` MAILSPOOF_LOG_LEVEL=DEBUG ./mailspoof start --port 2525 ``` 或修改 `lib/core.py`： ``` logging.basicConfig(level=logging.DEBUG) ``` ## 网络要求 ### 入站端口 | 端口 | 协议 | 描述 | |------|----------|-------------| | 2525 | TCP | 内置 SMTP 服务器 | | 25 | TCP | 直接 MX 中继（需要 root） | ### 出站端口 | 端口 | 协议 | 描述 | |------|----------|-------------| | 25 | TCP | 直接 MX 中继 | | 587 | TCP | STARTTLS 提交 | | 465 | TCP | SSL 提交 | | 53 | UDP | DNS MX 查找 | ### 防火墙规则 ``` # 允许内置 SMTP 服务器 sudo ufw allow 2525/tcp # 允许出站 SMTP（通常默认允许） sudo ufw allow out 587/tcp sudo ufw allow out 25/tcp ``` ## ASCII 截图示例 ### mailspoof list ``` MailSpoof Professional Email Security Assessment v1.2.0 --- Available Templates --- [1] CEO Fraud - Wire Transfer [Critical] [2] IT Support - Password Reset [High] [3] HR - Document Request [Medium] [4] Microsoft License Expired [High] [5] PayPal Security Alert [Critical] [+] Custom templates: 3 found in ~/.mailspoof/templates/ ``` ### mailspoof start ``` MailSpoof SMTP Server v1.2.0 Listening on 0.0.0.0:2525 Logs: /home/user/.mailspoof/audit.log Press Ctrl+C to stop. --- Interactive Spoofing Session --- Target email: victim@company.com Spoof from email: ceo@company.com Sender display name: CEO Subject: Urgent: Wire Transfer Required --- SMTP Relay Settings --- Use external SMTP relay? [y/N]: y SMTP host: smtp.gmail.com SMTP port [587]: 587 SMTP username: your.email@gmail.com SMTP password: ******* Use TLS/SSL? [Y/n]: ``` ### mailspoof report ``` --- Assessment Report --- Total Tests: 10 Successful: 7 Failed: 3 Success Rate: 70.0% Risk Level: HIGH Recommendations: - Implement SPF record for company.com - Enable DMARC enforcement (p=quarantine) - Conduct employee phishing awareness training Report saved: /home/user/.mailspoof/reports/report_20260604_120000.json ``` ## 版本历史 请参阅 [docs/CHANGELOG.md](docs/CHANGELOG.md) 获取完整的发行说明。 ## 支持 - 问题：[GitHub Issues](https://github.com/syed-sameer-ul-hassan/MailSpoof/issues) - 安全：请参阅 [SECURITY.md](SECURITY.md) - 讨论：[GitHub Discussions](https://github.com/syed-sameer-ul-hassan/MailSpoof/discussions) ## 许可证 基于 **Apache License 2.0** 授权。有关完整条款，请参阅 [LICENSE](LICENSE)。 ## 法律声明 MailSpoof 仅供**授权的安全测试、红队演练和教育目的**使用。在测试您不拥有的任何系统之前，请获得明确的书面许可。 **作者对任何滥用本工具的行为概不负责。** 用户有全责确保其对 MailSpoof 的使用符合其司法管辖区内的所有适用法律和法规。作者对因未经授权或非法使用本软件造成的任何损害、法律后果或伤害不承担任何责任。 ## 贡献 欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。 私下报告安全漏洞：请参阅 [SECURITY.md](SECURITY.md)。

标签：Python, 无后门, 网络安全, 请求拦截, 逆向工具, 隐私保护