Dr3mo/eml-analyser

# EML 分析器 一款专为 SOC 和应急响应分析师设计的本地、离线钓鱼邮件分类工具。它接收可疑的 `.eml` 文件，安全地解析其邮件头，并生成结构化的 HTML 报告，涵盖发件人身份、邮件身份验证、路由、安全网关判定、URL、附件以及威胁指示器。 专为“我刚收到一封转发来的可疑邮件，告诉我这是怎么回事”的瞬间而打造。 ## 功能 - **发件人身份分析** — 可见的发件人 (From)、信封发件人 (P1)、回复地址 (Reply-To)、DKIM 签名域以及 SPF `smtp.mailfrom` 域，具备三态对齐分类（精确匹配 / 注册域匹配 / 不匹配） - **邮件身份验证摘要** — SPF、DKIM 和 DMARC 结果，并附带针对常见未对齐模式的分析师注释 - **接收跃点分析** — 将每个跃点细分为发送主机、发送 IP、接收主机、接收 IP、TLS 状态和时间戳，其中跃点 1 为源点 - **安全网关判定** — 解析 Microsoft 的 `SCL`、`PCL`、`BCL`、`X-Forefront-Antispam-Report`、`X-Microsoft-Antispam`、`Auth-As` 以及 Google 的 `X-Gm-Spam` / `X-Gm-Phishy` 邮件头，并将其转换为人类可读的含义 - **源 IP 邮件头声明** — 提取 `X-Sender-IP`、`X-Originating-IP`、`X-Mailgun-Sending-Ip` 及类似邮件头，以便将其与 Received 链进行交叉比对，从而识别伪造行为 - **URL 提取与消除危险** — 兼容 CyberChef 的 URL 消除危险处理 (`hxxps[://]example[.]com`)，并具备可见文本与 href 不匹配检测功能 - **附件元数据** — 文件名、大小、SHA-256、MD5、扩展名分析、双重扩展名检测及风险等级。**负载 (Payload) 绝不写入磁盘。** - **加权风险评分** — 仅基于真实信号（DMARC 失败、URL 不匹配、高风险附件、网关 PHSH 判定、发件人域不匹配、SPF/DKIM 失败、SCL/BCL 评分）。贡献因素会在风险横幅下方列出，以确保透明度。 - **IOC 提取** — 域名、IP、URL、电子邮件地址和文件哈希，全部经过消除危险处理，可直接粘贴到工单或搜寻查询中 - 完成后，会在您的默认浏览器中**自动打开 HTML 报告** ## 截图 这些截图是根据 [`samples/`](samples/) 目录中的示例邮件生成的——对该目录下的邮件运行此工具将产生与您在此处看到的完全相同的报告。 以下是本项目包含的两封示例邮件（一封干净的正常邮件，一封明显的钓鱼邮件）生成的报告，旨在全面展示该工具的端到端输出效果。 ### 干净的正常邮件  *一封合法营销邮件的总体风险横幅、判定卡片和邮件头摘要——风险等级为低，无贡献因素。*  *对 Received 链进行逐跃点细分，清晰地分离了发送方和接收方，并在每个跃点上显示了 TLS 徽章。*  *解析出带有可读含义的 Microsoft SCL 和 BCL 分数，以及用于交叉比对的源 IP 邮件头声明表。* ### 钓鱼邮件  *高风险横幅，带有“贡献因素”面板，列出了每个触发的指标及其权重——评分背后具有完全的透明度。*  *“发件人身份”卡片显示了可见的发件人、信封发件人、回复地址和 DKIM 域名——当它们不一致时会发出不匹配警告。*  *URL 表格标记了可见文本与实际 href 不匹配的情况——可见链接声称指向 `microsoftonline.example`，但实际目的地是一个凭据收集主机。*  *附件部分显示了可疑 HTML 附件的元数据、哈希值和风险说明——负载 (Payload) 绝不会写入磁盘。*  *可直接复制粘贴的 IOC 区块，包含已消除危险的域名、IP、URL、电子邮件地址和文件哈希。* ## 安全模型 此工具专为在分析师工作站上运行而设计，不会增加额外风险： - 附件**绝不写入磁盘**。负载 (Payload) 仅在内存中解码以进行哈希处理，随后即被丢弃。 - 该工具**不发起任何网络请求**。没有 VirusTotal 查询，没有 DNS 解析，没有 URL 抓取——一切都是纯本地的。 - 任何地方都**没有动态代码执行**。不对源 `.eml` 文件使用 `eval`、`exec`、`subprocess`、`os.system` 或 `os.startfile`。 - **报告中的所有 URL 均已消除危险**，因此即使您在浏览器中意外点击，也不会连接到目标地址。 - **邮件解析器使用 Python 的 `policy.compat32`**，以增强对畸形输入的鲁棒性。 如需在沙箱中提取附件负载（属于较高风险的操作），建议使用专门的独立工具——这款分析器特意保持在只读的分类分析界限内。 ## 环境要求 - Python 3.8 或更高版本 - 可选：`beautifulsoup4`，用于改进邮件正文中的 HTML/URL 解析（如果未安装，则回退使用正则表达式） ## 安装说明 克隆或下载本代码库，然后可选地安装推荐的依赖项： ``` pip install -r requirements.txt ``` 就这样。该工具是一个独立的单文件脚本。 您可以立即对包含的示例邮件之一运行该工具，以查看其输出效果： ``` python eml_analyser.py samples/sample_benign.eml python eml_analyser.py samples/sample_phishing.eml ``` ## 用法 基本用法： ``` python eml_analyser.py suspicious.eml ``` 该工具将解析邮件，在终端打印快速摘要，在输入文件旁边生成 HTML 报告（例如 `suspicious_analysis.html`），并在您的默认浏览器中将其打开。 ### 命令行选项 | 标志 | 用途 | | ----------------- | ----------------------------------------------------------- | | `--html PATH` | 自定义 HTML 报告的输出路径 | | `--json PATH` | 同时写入一个包含所有已解析数据和 IOC 的 JSON 文件 | | `--no-open` | 不自动打开浏览器（默认是打开） | | `-q`, `--quiet` | 隐藏终端摘要 | ### 示例 仅进行分类并打开报告： ``` python eml_analyser.py suspicious.eml ``` 批处理模式，不打开浏览器，输出 JSON 供其他工具使用： ``` python eml_analyser.py suspicious.eml --no-open --json iocs.json -q ``` 自定义输出位置： ``` python eml_analyser.py suspicious.eml --html C:\cases\ticket-1234\report.html ``` ## 报告内容说明 HTML 报告是一份深色模式的单文件文档（无外部资源，无 JavaScript），包含以下部分： 1. **邮件头摘要** — 主题、发件人、收件人、日期、邮件 ID、身份验证摘要 2. **总体风险横幅** — 高 / 中 / 低，并附带贡献因素 3. **分析师判定辅助** — 方便快速浏览的判定卡片 4. **发件人身份** — 包含对齐分析 5. **邮件身份验证** — SPF / DKIM / DMARC 表格 6. **邮件路由** — 包含发送方/接收方分离和 TLS 状态的逐跃点细分 7. **安全网关判定** — Microsoft/Google 的垃圾邮件和钓鱼评分 8. **源 IP 邮件头声明** — 用于伪造检测的交叉比对表 9. **发现的 URL** — 包含消除危险后的版本和不匹配标记 10. **附件** — 元数据和风险评估（不写入负载） 11. **威胁指示器 (IOC)** — 可直接复制粘贴的 IOC 区块 12. **原始邮件头** — 可折叠的完整邮件头视图 ## 风险评分 仅基于真实信号。仅因存在 URL 或附件（其他工具中常见的误报源）不会获得任何分数。 | 权重 | 信号 | | -------------- | --------------------------------------------------------------------------------------------------------------------------------- | | **3 (强)** | DMARC 失败、URL 显示/目的地不匹配、高风险附件（可执行文件/宏）、网关 PHSH/SPOOF/MALW 判定、SCL >= 9 | | **2 (中)** | 发件人域不匹配、SPF 失败/软失败、DKIM 失败、SCL 5-8 | | **1 (弱)** | 无明确高风险指标的可疑附件扩展名 | 阈值：**5+ = 高**，**2 到 4 = 中**，**0 到 1 = 低**。 所有贡献因素及其各自的权重都会在报告的风险横幅下方列出，以便分析师清楚地了解分数是如何得出的。 ## 本工具未涵盖的功能 为保持其专注性和安全性而特意设定的范围限制： - 不将附件负载提取到磁盘（请使用单独的沙箱工具） - 不进行网络查询（VirusTotal、Whois、DNS、信誉等）——保持完全离线 - 不进行恶意软件引爆或执行 - 不进行实时监控或邮箱集成 - 不提供 API——仅支持 CLI ## 开发说明 该工具是一个单一的 Python 文件，没有运行时状态、没有多线程、也没有外部框架依赖。它遵循一个直接的流水线：解析 EML、分析每个部分、生成报告、打开浏览器。每个部分（发件人、身份验证、跃点、Microsoft 邮件头、链接、附件、IOC）都是一个独立的函数，该函数接收已解析的邮件并返回一个字典，从而方便在其他场景中复用各项独立的分析。 用于 URL、IPv4 和 IPv6 的正则表达式模式被设计为抗粘贴干扰（没有行尾锚点、没有海象运算符、没有晦涩的特殊字符），从而确保源代码在经过复制粘贴和下载往返后依然能够保持完好无损。 ## 许可证 本项目基于 MIT 许可证授权——详情请参阅 [LICENSE](LICENSE) 文件。 ## 免责声明 本工具仅作为分析师的辅助手段提供。它不能替代专用的邮件安全平台、沙箱或专业判断。判定结果和风险评分均基于启发式方法，在分类分析时应将其视为众多信号中的一种。

标签：EML解析, 多模态安全, 威胁情报提取, 安全运营, 库, 应急响应, 扫描框架, 文档结构分析, 电子邮件安全, 逆向工具, 钓鱼邮件分析