YonithJamad/Threat-Scope-Email-Header-Analysis

# ThreatScope - 邮件头分析 ThreatScope 是一个先进的专用网络安全平台，旨在简化对可疑邮件、钓鱼攻击和高级持续性威胁（APT）的调查。通过自动化提取和分析邮件路由头，它在统一的现代 Web 仪表板中提供无缝扫描、地理空间跟踪和可操作的威胁情报。 该应用完全**无状态且安全**，直接加载分析仪表板，无需任何登录、注册或后端数据库配置。 ## 🛠️ 功能与能力 该平台编排以下能力以执行全面的邮件侦察： * **头解析与提取：** * **邮件模块：** 原生解析标准 `.eml` 文件和原始文本头。 * **Extract-Msg：** 解码复杂的 Microsoft Outlook `.msg` 文件。 * **提取字段：** 自动提取并格式化以下元数据字段： * **Subject：** 邮件的主题行。 * **From：** 发件人的姓名和邮箱地址。 * **To：** 主要收件人的姓名和邮箱地址。 * **Date：** 邮件发送的日期和时间。 * **Message-ID：** 发送邮件服务器生成的唯一标识符。 * **Return-Path：** 退信和投递通知发送到的地址。 * **MIME-Version：** 用于构建邮件内容的格式标准。 * **References：** 对话线程中先前邮件的 Message-ID，用于追踪历史。 * **In-Reply-To：** 此邮件所回复邮件的 Message-ID。 * **Content-Type：** 邮件的格式和媒体类型（如 HTML、纯文本、多部分）。 * **X-Microsoft-Antispam-Mailbox-Delivery：** Outlook 特定的反垃圾邮件判定、SCL 和投递标签。 * **Domain DNS (MX)：** DNS 状态，显示发件人域名是否具有有效的邮件交换记录。 * **身份验证与校验：** * **SPF/DKIM/DMARC 检查：** 评估头中的域对齐和身份验证标记以识别伪造尝试。 * **DNS 解析：** 检查 MX 记录以验证域名的合法性。 * **启发式规则引擎：** 采用 7 条规则的评分引擎，评估身份验证状态、缺失记录和域有效性，以计算确定性威胁评分（0-100）。 * **侦察与地理定位：** * **IP 地理位置（ipwho.is）：** 确定来源 IP 地址的地理位置、ISP 和 ASN。 * **LeafletJS 地图：** 在交互式地图上动态标注邮件的地理来源。 * **威胁情报：** * **IP 信誉查询：** 即时搜索任何 IP 地址以收集 ISP、ASN、类型和地理数据。 * **实时威胁情报源：** 在仪表板内聚合实时网络安全威胁公告和文章。 ## ⚙️ 规则引擎与误报特征 ### 1. 它处理多少条规则？ [main.py](main.py) 中的威胁评分引擎是一个确定性的基于规则的系统。它处理 **7 条核心评估规则**： * **SPF 状态规则：** 检查 SPF 验证是否失败（通过 vs. 失败）。向威胁评分增加 **30 分**。 * **DKIM 状态规则：** 检查 DKIM 验证是否失败。向威胁评分增加 **30 分**。 * **DMARC 状态规则：** 检查 DMARC 验证是否失败。向威胁评分增加 **40 分**。 * **SPF 缺失规则：** 检查 SPF 记录是否缺失（none）。向威胁评分增加 **10 分**。 * **DMARC 缺失规则：** 检查 DMARC 记录是否缺失。向威胁评分增加 **10 分**。 * **双重缺失警告规则：** 检查 SPF 和 DKIM 身份验证结果是否同时缺失（none），将其标记为可疑。 * **域有效性规则：** 尝试解析发件人域的 MX 记录以识别无效或缺失的邮件服务器。 这些计算和规则在 `calculate_threat_score` 和 `generate_ai_explanation` 函数中处理。 ### 2. 误报率是多少？ 由于 ThreatScope 是一个无状态的本地工具，不连接中央数据库或收集遥测数据，因此没有记录经验性的误报率（FPR）。 然而，从架构角度来看，引擎的理论误报特征由以下因素定义： * **启发式阈值：** 如果评分 $\ge 20$，工具将邮件标记为"可疑"；如果 $\ge 60$，则标记为"高风险"。缺少记录的邮件（如没有 SPF/DMARC 的新域名）将获得 `20/100` 的评分（"可疑"），这可能导致对合法但配置不佳的域名产生中等误报率。 * **头转发敏感性：** `parse_auth_results` 中的解析引擎读取接收邮件服务器生成的 `Authentication-Results` 头。如果邮件被合法转发（例如通过邮件列表或转发器），SPF 检查自然会失败，即使邮件是干净的，也会提高威胁评分。 * **无主动加密验证：** 工具不对 DKIM 签名执行实时加密验证或对传入 IP 执行主动 SPF 检查；它信任头中记录的判定。如果下游邮件服务器对记录分类错误，ThreatScope 将继承该错误。 ## 1. 如何执行项目 ### 前置条件 确保系统上安装了 **Python 3.8+**。 ### 执行步骤 1. **克隆仓库：** git clone https://github.com/YonithJamad/Threat-Scope-Email-Header-Analysis.git cd Threat-Scope-Email-Header-Analysis 2. **创建并激活虚拟环境：** **Windows 系统：** python -m venv venv .\venv\Scripts\activate **Linux / macOS 系统：** python3 -m venv venv source venv/bin/activate 3. **安装依赖：** pip install -r requirements.txt 4. **运行服务器：** 在项目文件夹中打开终端并运行： python -m uvicorn main:app --reload 5. 终端将显示 `INFO: Uvicorn running on http://127.0.0.1:8000`。 6. 打开 Web 浏览器并导航至：**[http://127.0.0.1:8000](http://127.0.0.1:8000)**。 7. 您将直接进入 ThreatScope 仪表板。 ## 2. 项目文件结构 项目结构分为清晰的后端 API 端点和现代前端组件： ### 后端逻辑（`main.py`） - **`main.py`** 是核心 FastAPI 应用。它提供静态文件（`index.html`、`style.css`、`script.js`）并处理分析 API 路由。 - 它解析原始邮件头、处理上传的文件（`.eml` 和 `.msg`）、运行身份验证检查启发式规则、执行 DNS 解析、从 `ipwho.is` 获取 IP 详情，并抓取实时威胁情报源。 ### 前端 UI 组件 - **`index.html`**：定义单页应用仪表板布局，包括分析表单、交互式地图容器、路由时间线、提取的元数据网格和威胁情报源。 - **`script.js`**：驱动用户体验。它处理文件上传拖放操作、向后端发起异步 API 请求、初始化和更新 Leaflet 地图、渲染路由时间线，并管理本地存储历史。 - **`style.css`**：提供优质的网络安全美学，包括基于系统偏好的暗/亮模式自适应、悬停效果和响应式 CSS 变量。 ### 数据存储 - **`localStorage`**：为保持平台无状态和私密性，您的搜索和分析历史直接保存在本地浏览器存储（`localStorage`）中，绝不会传输或保存到服务器数据库。 ## 3. Render 部署 由于该应用完全无状态，不需要外部数据库（如 SQLite 或 Postgres）或 SMTP 凭据，因此在 **Render** 等云平台上托管极为简单： 1. 在 Render 上创建一个新的 **Web Service**。 2. 关联您的 GitHub 仓库。 3. 配置构建和启动命令： - **构建命令：** `pip install -r requirements.txt` - **启动命令：** `python -m uvicorn main:app --host 0.0.0.0 --port $PORT` 4. 部署！服务将立即启动并加载公共仪表板。

标签：APT, CDN识别, DAST, DKIM, DMARC, DNS查询, EML解析, ESC4, Header, HTTP/HTTPS抓包, IP地理定位, MSG解析, MX记录, OSINT, PB级数据处理, SPF, Syscall, Web开发, 仪表盘, 取证, 威胁情报, 威胁指标IoC, 安全解决方案, 安全运维, 安全运营, 开发者工具, 态势感知, 恶意软件分析, 扫描框架, 数据可视化, 数据提取, 无状态应用, 现代Web界面, 网络安全, 自定义脚本, 调试辅助, 逆向工具, 邮件头, 邮件安全, 钓鱼检测, 防火墙, 隐私保护