glenjr009/Email-Spoofing-Detector

# IDENTI_ALIGN // THREAT_STREAM ## 🛡️ 具备威胁情报与机器学习功能的异步邮件取证网关 **IDENTI_ALIGN // THREAT_STREAM** 是一个工程导向的网络安全项目，旨在通过原始 `.eml` 文件分析、确定性邮件认证检查、开源情报 (OSINT) 信誉情报以及基于机器学习的内容分类，来检测**邮件欺骗**、**身份冒充**和**钓鱼异常**。 该系统结合了 **SPF**、**DKIM**、**DMARC 风格的身份对齐**、**AbuseIPDB 威胁情报** 以及一个 **多项式朴素贝叶斯机器学习分类器**，为每封分析的邮件生成结构化的风险评分。 ## 👨‍💻 作者 **Glen Fernandes** 网络安全爱好者 | Web 开发者 | 计算机科学与工程学士在读 ## 📌 项目概述 邮件欺骗和钓鱼攻击常常通过伪造发件人身份、操纵邮件头以及通过看似合法的通信渠道投递欺骗性内容来滥用信任。 此项目作为一个**邮件取证网关**，处理原始 `.eml` 文件，并通过多个独立的威胁层评估每封邮件。 升级后的架构现在包含了一个**机器学习启发层**，该层使用 TF-IDF 文本特征提取和多项式朴素贝叶斯分类器，基于概率来评估类似钓鱼的语言模式，而不是仅仅依赖静态关键词匹配。 ## 🎯 目标 本项目的主要目标是： - 🔍 分析原始 `.eml` 邮件文件以发现欺骗和钓鱼指标 - 🛡️ 使用 SPF 检查验证发件人基础设施 - 🧾 检测可见发件人域名与技术发件人域名之间的身份不匹配 - 🔐 验证基于 DKIM 的密码学完整性 - 🌐 集成 AbuseIPDB 以获取实时网络信誉评分 - 🤖 应用机器学习进行基于概率的钓鱼内容检测 - ⚡ 使用异步工作进程并发处理多个邮件样本 - 📊 生成清晰的 SECURE / CAUTION / THREAT 分类 - 📤 导出结构化的取证报告以供审查和事件响应 ## ✨ 主要特性 | 特性 | 描述 | |---|---| | ⚡ 异步处理 | 使用 `ThreadPoolExecutor` 配合 20 个并行工作线程进行并发邮件分析 | | 📤 手动诊断 | 支持通过 Web 界面直接上传 `.eml` 文件 | | 📁 自动批量摄入 | 监视 `/TEST_SAMPLES` 目录以进行批量邮件处理 | | 🤖 机器学习内容分类 | 使用 `TfidfVectorizer` 和 `MultinomialNB` 进行类似钓鱼的内容检测 | | 🧮 拉普拉斯平滑 | 使用 `alpha=1.0` 以稳定处理未登录词表的概率 | | 🧾 SPF 验证 | 根据 DNS 记录检查发件人基础设施授权 | | 🔐 DKIM 验证 | 验证邮件密码学签名 | | 🛡️ 身份对齐 | 比较 RFC 5322 `From` 头与技术 `Return-Path` 域名 | | 🌐 OSINT 威胁情报 | 查询 AbuseIPDB 以获取实时中继 IP 信誉 | | 🧠 L1 信誉缓存 | 在内存中存储重复的 IP 查询结果，以提高速度并减少 API 调用 | | 📊 仪表板可视化 | 使用 Chart.js 进行实时威胁可视化 | | 🎨 响应式 UI | 使用 Bootstrap 5 构建简洁的赛博暗色仪表板布局 | | 📤 CSV 导出 | 导出结构化的分析报告以供事件响应工作流使用 | ## 🧱 技术栈 | 层级 | 技术 | |---|---| | 🐍 核心框架 | Python 3.13+, Flask | | 🗂️ 会话管理 | Flask-Session, 基于文件系统的会话 | | 🤖 机器学习 | pandas, scikit-learn | | 🧠 机器学习向量化 | TfidfVectorizer | | 📊 机器学习分类器 | MultinomialNB | | 🚀 生产级 WSGI 服务器 | Waitress | | 📧 协议验证 | pyspf, dkimpy, dnspython | | 🌐 威胁情报 | requests, AbuseIPDB REST API | | ⚡ 并发 | ThreadPoolExecutor | | 🎨 前端 | Bootstrap 5 | | 📈 可视化 | Chart.js | | 📤 报告 | CSV 导出 | ## 🏗️ 架构亮点 ### ⚡ 1. 异步核心 该应用程序使用由 `ThreadPoolExecutor` 驱动的并发工作进程模型。 ``` ThreadPoolExecutor(max_workers=20) ``` 这使得系统能够并行处理多个邮件样本，而不是顺序扫描。 优点： - 更快的批量邮件处理速度 - 在批量摄入期间具有更好的吞吐量 - 在手动诊断期间具有更好的响应能力 - 更逼真的企业级网关行为 ### 🤖 2. 多项式朴素贝叶斯机器学习集成 升级后的检测引擎包含了一个基于机器学习的内容检查层。 机器学习流程使用： - `TfidfVectorizer` 用于文本特征提取 - `MultinomialNB` 用于基于概率的钓鱼分类 - `alpha=1.0` 拉普拉斯平滑以实现稳定的分类 该模型将邮件正文文本处理为 TF-IDF 特征向量，并根据学习到的恶意文本模式计算恶意内容的概率。 ``` TfidfVectorizer() MultinomialNB(alpha=1.0) ``` 此升级通过允许系统从数学上评估可疑文本模式，从而超越静态关键词检查，提高了检测能力。 ### 🧮 3. 拉普拉斯平滑 分类器使用拉普拉斯平滑，参数为： ``` alpha=1.0 ``` 这确保未登录或独特的词汇术语不会导致概率计算崩溃为零。 优点： - 更好地处理未登录的钓鱼词汇 - 改善边界稳定性 - 在测试期间提供更可靠的分类 - 增强对多样邮件内容的鲁棒性 ### 🚀 4. Waitress 生产部署 该项目使用 **Waitress** 作为生产级 WSGI 服务器，而不是仅依赖 Flask 的开发服务器。 Waitress 被配置为多线程套接字绑定，以支持更高的并发吞吐量，并减少 Windows 套接字冲突，例如： ``` WinError 10038 ``` ### 🌐 5. 具有 L1 缓存的 OSINT 威胁情报 该系统与 AbuseIPDB 集成，以评估提取的发件人或中继 IP 地址的信誉。 为了提高效率，一个内存中的 **L1 缓存** 存储了先前查询的 IP 信誉结果。 优点： - 更快的重复扫描 - 减少 AbuseIPDB API 调用 - 更好的速率限制管理 - 改善演示可靠性 - 更强的批量处理性能 ## 🧮 多信号风险矩阵 检测引擎使用五个独立的威胁层，计算从 `0` 到 `100+` 分的动态风险评分。 | # | 威胁层 | 权重 | 检测逻辑 | |---|---|---:|---| | 1 | 🧾 基础设施保护层 | `+20` | 执行 SPF 验证，对照域 DNS 记录验证发送服务器是否被授权 | | 2 | 🛡️ 身份验证层 | `+25` | 比较 RFC 5322 `From` 头与 `Return-Path` 技术源域，以检测身份差异 | | 3 | 🔐 密码学完整性层 | `+15` | 验证 DKIM 数字密码学印章，以检测缺失或无效的签名 | | 4 | 🌐 全球情报层 | `0 到 +50` | 应用 AbuseIPDB 返回的实时滥用置信度评分 50% 的罚分 | | 5 | 🤖 机器学习启发层 | `0 到 +30` | 基于多项式朴素贝叶斯恶意分类置信度百分比应用动态罚分 | ## 🚦 风险分类阈值 | 最终得分 | 分类 | 状态颜色 | 含义 | |---:|---|---|---| | `< 30` | 🟢 SECURE | 绿色 | 低风险邮件，无重大欺骗、钓鱼或信誉指标 | | `30 - 59` | 🟡 CAUTION | 黄色 | 可疑邮件，需要手动审查 | | `60+` | 🔴 THREAT | 红色 | 高风险邮件，可能涉及欺骗、冒充或钓鱼行为 | ## 📁 项目目录结构 ``` IDENTI_ALIGN-THREAT_STREAM/ │ ├── app.py │ └── Flask routing, file processing pipelines, session engine, and Waitress setup │ ├── detector.py │ └── ML vectorizer initialization, multi-signal scoring matrix, and L1 reputation cache │ ├── generate_varied.py │ └── Data generation utility mimicking 7 distinct multi-vector testing profiles │ ├── flask_session/ │ └── Internal filesystem-backed session architecture files │ ├── TEST_SAMPLES/ │ └── Watched batch ingestion path for automated .eml processing │ ├── requirements.txt │ └── Python dependency list │ └── README.md └── Project documentation ``` ## ⚙️ 安装指南 请按照以下步骤在本地设置并运行项目。 ## ✅ 前置条件 请确保已安装以下内容： - 🐍 Python 3.13 或更高版本 - 🌿 Git - 📦 pip - 🌐 现代 Web 浏览器 - 🔑 AbuseIPDB API 密钥 检查 Python 版本： ``` python --version ``` 或： ``` python3 --version ``` 检查 pip 版本： ``` pip --version ``` ## 📥 1. 克隆仓库 ``` git clone https://github.com/glenjr009/Email-Spoofing-Detector.git cd Email-Spoofing-Detector ``` ## 🧪 2. 创建虚拟环境 建议使用虚拟环境来隔离项目依赖。 ### Windows PowerShell ``` python -m venv venv ``` 激活虚拟环境： ``` .\venv\Scripts\Activate.ps1 ``` 如果 PowerShell 阻止脚本执行，请运行： ``` Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser ``` 然后再次激活： ``` .\venv\Scripts\Activate.ps1 ``` ### Linux / macOS ``` python3 -m venv venv ``` 激活虚拟环境： ``` source venv/bin/activate ``` ## 📦 3. 安装依赖项 安装所需的依赖项： ``` pip install flask flask-session pyspf dkimpy dnspython requests waitress pandas scikit-learn ``` 或者，如果存在 `requirements.txt` 文件： ``` pip install -r requirements.txt ``` 推荐的 `requirements.txt`： ``` flask flask-session pyspf dkimpy dnspython requests waitress pandas scikit-learn ``` ## 🔑 4. 配置 AbuseIPDB API 密钥 此项目使用 AbuseIPDB 进行基于实时 OSINT 的 IP 信誉评分。 为您的 API 密钥创建一个环境变量。 ### Windows PowerShell ``` $env:ABUSEIPDB_API_KEY="YOUR_API_KEY_HERE" ``` ### Linux / macOS ``` export ABUSEIPDB_API_KEY="YOUR_API_KEY_HERE" ``` ## ▶️ 5. 运行应用程序 启动应用程序： ``` python app.py ``` 或： ``` python3 app.py ``` ## 🌐 6. 打开 Web 界面 启动服务器后，打开浏览器并访问： ``` http://127.0.0.1:5000/ ``` # 🧭 操作模式 该项目支持两种主要的工作流： 1. 📤 手动诊断 2. 📁 自动摄入管道 ## 📤 模式 1：手动诊断 手动诊断允许用户通过 Web 界面直接上传 `.eml` 文件。 ### 工作流 1. 启动应用程序。 ``` python app.py ``` 2. 打开仪表板。 ``` http://127.0.0.1:5000/ ``` 3. 上传一个或多个 `.eml` 文件。 4. 系统执行： - SPF 验证 - DKIM 验证 - 身份对齐检查 - AbuseIPDB 信誉查询 - 基于机器学习的内容分类 - 最终加权评分 5. 查看结果： - 🟢 SECURE - 🟡 CAUTION - 🔴 THREAT 6. 如有需要，导出取证 `.csv` 报告。 ## 📁 模式 2：自动摄入管道 自动管道从监视的批量目录扫描邮件。 ### 工作流 1. 将 `.eml` 文件放入： ``` TEST_SAMPLES/ ``` 2. 启动应用程序。 ``` python app.py ``` 3. 系统从监视目录摄入文件。 4. 异步工作进程池并发处理邮件。 5. 结果显示在仪表板中。 6. 导出合并的 CSV 报告以供审查。 ## 🧪 生成多样化的测试样本 该项目包含 `generate_varied.py`，一个用于生成多个模拟邮件测试配置的实用脚本。 运行： ``` python generate_varied.py ``` 或： ``` python3 generate_varied.py ``` 生成器可以模拟不同的测试配置，例如： - SPF 失败 - DKIM 缺失 - DKIM 无效 - 身份不匹配 - 可疑内容 - 恶意中继信誉 - 多向量威胁组合 ## 🖥️ 模拟管道遥测输出 分析期间的结构化事务日志示例： ``` [INIT] IDENTI_ALIGN // THREAT_STREAM starting forensic gateway... [INIT] Flask session engine loaded using filesystem-backed storage [INIT] Waitress WSGI server initialized with multi-threaded socket binding [INIT] ML pipeline loading TfidfVectorizer and MultinomialNB(alpha=1.0) [INIT] Threat intelligence cache initialized: L1_MEMORY_CACHE [INGEST] Source: TEST_SAMPLES/ [INGEST] Detected file: invoice_security_alert.eml [QUEUE] Submitted job to ThreadPoolExecutor worker pool [WORKER-07] Parsing RFC 5322 headers... [WORKER-07] Extracted From: support@example-bank.com [WORKER-07] Extracted Return-Path: relay@unknown-mailer.net [WORKER-07] SPF result: FAIL | Penalty: +20 [WORKER-07] DKIM result: MISSING | Penalty: +15 [WORKER-07] Identity alignment: MISMATCH | Penalty: +25 [WORKER-07] AbuseIPDB lookup: 42 confidence | Penalty: +21 [WORKER-07] ML phishing probability: 73% | Penalty: +22 [WORKER-07] Final risk score: 103 [WORKER-07] Classification: THREAT [EXPORT] CSV forensic report generated successfully [STATUS] Dashboard telemetry updated ``` ## 📊 风险输出示例 ``` Email File: invoice_security_alert.eml Classification: THREAT Final Score: 103 Triggered Signals: - SPF Check Failure: +20 - Identity Verification Mismatch: +25 - Missing DKIM Signature: +15 - AbuseIPDB Reputation Penalty: +21 - ML Phishing Confidence Penalty: +22 Recommendation: This email should be treated as a high-risk phishing or spoofing attempt. Do not click embedded links or download attachments. Escalate the sample for manual incident response review. ``` ## 📤 CSV 导出报告 取证导出中心为扫描的邮件生成结构化的 `.csv` 报告。 可能的报告字段： | 字段 | 描述 | |---|---| | 📄 文件名 | 被分析的 `.eml` 文件的名称 | | 👤 发件人地址 | RFC 5322 可见的发件人身份 | | 🔁 返回路径 | 技术返回路径域名 | | 🌐 源 IP | 提取的发件人或中继 IP 地址 | | 🧾 SPF 结果 | SPF 通过/失败状态 | | 🔐 DKIM 结果 | DKIM 有效/缺失/无效状态 | | 🛡️ 身份匹配 | 发件人身份是否与技术源匹配 | | 📡 滥用评分 | AbuseIPDB 置信度评分 | | 🤖 机器学习置信度 | 基于机器学习的钓鱼概率 | | 📊 风险评分 | 最终计算的风险值 | | 🚦 分类 | SECURE, CAUTION 或 THREAT | ## 🧠 检测逻辑总结 该系统不依赖单一的检测信号。 相反，它结合了确定性验证和概率性机器学习评分： - 🧾 SPF 验证发件人基础设施 - 🛡️ 身份对齐检测冒充差异 - 🔐 DKIM 检查密码学完整性 - 🌐 AbuseIPDB 评估网络信誉 - 🤖 MultinomialNB 估计钓鱼内容概率 - ⚡ ThreadPoolExecutor 实现并发高容量扫描 这种分层方法提供了更可解释和实用的邮件取证评估。 ## 🚀 未来增强 计划中的改进包括： - 🔗 已验证接收链 (ARC) 支持 - 🧠 基于 Redis 的 L2 信誉缓存 - 📩 DMARC RUA XML 报告解析器 - 📎 邮件附件扫描 - 🔍 嵌入式 URL 提取和钓鱼域名分析 - 🌐 VirusTotal 或 URLScan.io 集成 - 🗂️ 案例管理和调查标记 - 👥 基于角色的分析员仪表板 - 📄 PDF 事件报告导出 - 🐳 Docker 部署支持 - ⚙️ 具有自动化测试执行的 CI/CD 管道 - 🧪 评分和协议模块的单元测试 - 📬 使用 IMAP 进行实时邮箱摄入 - 📈 使用带标签的钓鱼数据集进行模型重训练的管道 ## 🎓 学术相关性 该项目展示了网络安全和软件工程概念的实际应用，包括： - 邮件认证协议 - 数字取证 - 威胁情报集成 - 基于机器学习的文本分类 - TF-IDF 特征提取 - 朴素贝叶斯分类 - 并发编程 - Web 应用程序开发 - 事件响应报告 - 基于风险的分类系统 ## ⚠️ 免责声明 本项目严格为**教育、学术、作品集展示和防御性网络安全目的**而开发。 不得用于： - 钓鱼 - 发送垃圾邮件 - 未经授权的测试 - 生成恶意邮件 - 攻击第三方系统 - 绕过安全控制 - 任何违反法律、政策或道德网络安全实践的活动 本项目的目的是帮助用户理解、检测和防御邮件欺骗、钓鱼和身份冒充攻击。 ## 📄 许可证 本项目基于 **MIT 许可证** 发布。 您可以为教育和研究目的自由使用、修改和分发本项目，但需注明原作者。 ## 🔗 仓库 使用以下命令克隆项目： ``` git clone https://github.com/glenjr009/Email-Spoofing-Detector.git ``` 如果您喜欢这个项目或觉得它有用，请考虑在 GitHub 上给它一个 ⭐ 以支持未来的开发。 ## 💡 最终说明 **IDENTI_ALIGN // THREAT_STREAM** 通过结合协议验证、OSINT 威胁情报、异步处理和基于机器学习的钓鱼内容分析，提供了一种结构化且可解释的邮件欺骗检测方法。 该项目展示了现代邮件取证系统如何能够超越静态关键词启发式方法，并采用一个可扩展、可解释且适用于现实世界网络安全工作流的分层检测模型。

标签：AMSI绕过, Apex, API集成, DKIM验证, DMARC对齐, .eml文件分析, ESC4, meg, OSINT, SPF检查, 信息安全, 可观测性, 威胁情报, 威胁检测, 并发计算, 开发者工具, 异常检测, 异步处理, 技术栈, 文本分类, 机器学习, 欺诈检测, 欺骗检测, 法医分析, 滥用检测, 电子邮件分析, 电子邮件安全, 网络安全, 身份冒充, 身份对齐, 逆向工具, 钓鱼检测, 隐私保护, 零信任安全, 风险评分