Un-9oon/mailguard-pro

## 📖 概述 **MailGuard Pro** 是一个为安全运营中心 (SOC) 打造的自托管平台。员工将可疑邮件转发到共享邮箱；MailGuard Pro 会像专家分析师那样检查每一封邮件——但只需几秒钟，保持一致性，且能大规模处理——进而**防范**攻击。 它执行四项任务： 1. **分析邮件** — 一个多阶段的取证 pipeline（标头身份验证、内容、链接、发件人信誉、附件）会生成一个透明的 **0–100 威胁评分**，并完整解释*原因*。 2. **追踪攻击者基础设施** — **Brand Recon** 会在仿冒品牌的域名*被武器化之前*，主动发现已注册的相似域名。 3. **执行保护** — 四项企业级控制措施：威胁情报源、**DNS sinkhole**、**Secure Web Gateway** 以及 **SPF/DKIM/DMARC 强制验证**。 4. **呈现一切** — 在一个实时的、深色/浅色主题的**专业 SOC 仪表板**上展示所有信息。 ## 📸 截图 ## ✨ 功能 ### 邮件分析 - **标头取证** — SPF / DKIM / DMARC 验证（硬失败与软失败），完整的转发链解析，From/Reply-To/Return-Path 欺骗检测。 - **内容分析** — 紧急性、社会工程学策略、凭据/支付请求、通讯录检测。 - **链接深度分析** — URL 伪装、typosquatting (Levenshtein)、同形异义字/IDN、短链接、滥用的 TLD、重定向链、WHOIS 域名年龄、DNS/IP 分类、实时黑名单匹配。 - **域名情报** — 针对 24 个品牌注册表进行品牌冒充检测；**本地托管钓鱼**检测（私有 IP 上的钓鱼工具包）。 - **附件分析** — 危险类型、双重扩展名 (`invoice.pdf.exe`)、启用宏的 Office 文件、SHA-256 哈希。 - **透明评分** — 0–100 分，带有每个信号的详细分析和 5 个严重性等级区间。 ### 主动追踪 - **Brand Recon** — 解析品牌的真实域名，验证其是否活跃，生成 typosquat/combosquat 排列组合，并报告哪些相似域名**实际上已被注册**。 - **URL Inspector** — 对任何单个链接（甚至是全新链接）给出判定结论（钓鱼 / 可疑 / 合法）。 ### 企业防御 - **威胁情报源** — OpenPhish + URLhaus（+ 可选的 PhishTank）→ 本地黑名单。 - **DNS sinkhole** — 无依赖的 UDP DNS 服务器，使用安全的“围墙花园”页面响应被封锁的域名；导出至 **hosts / Pi-hole / dnsmasq / BIND RPZ**。 - **Secure Web Gateway** — 实时的允许/拦截策略（黑名单、新注册域名、被滥用的 TLD、typosquat）。 - **邮件身份验证强制执行** — SPF/DKIM/DMARC 安全态势评级 (A–F) + 入站拒绝对受保护域名的欺骗。 ### 平台 - 通过 **Server-Sent Events** 实时更新、深色/浅色主题、CSV 导出、分析师判定校准、误报防护机制。 ## 🚀 快速开始 开箱即用地运行于 **demo 模式**（内置示例邮件，无需凭据）。 ``` git clone https://github.com/Un-9oon/mailguard-pro.git cd mailguard-pro cp .env.example .env # DEMO_MODE=true by default npm install npm rebuild better-sqlite3 # build the native DB module (once) npm start ``` 打开 **http://localhost:3000** 并点击 **Scan Inbox**。 🎉 ### 连接真实的 Gmail 收件箱（可选） 1. 启用两步验证并创建一个 **App Password** (`myaccount.google.com/apppasswords`)。 2. 在 `.env` 中：设置 `IMAP_USER`、`IMAP_PASSWORD` 以及 `DEMO_MODE=false`。 3. 重启 — MailGuard 将轮询收件箱并自动分析新邮件。 ## 🧠 工作原理 ``` Email → Parser → ┌─ Header forensics (SPF/DKIM/DMARC, spoofing, routing) ├─ Content analysis (urgency, social engineering) ├─ Link analysis (typosquat, redirects, WHOIS, blocklist) ├─ Domain intel (brand impersonation, locally-hosted kits) ├─ Attachment scan (dangerous types, macros, hashes) └─ Email-auth enforcement (protected-domain spoofing) ↓ Scoring engine (0–100, transparent weights) ↓ Verdict + breakdown → SQLite → live SSE → dashboard ``` 每个阶段都是故障隔离的：单一故障（例如 WHOIS 超时）绝不会中止整个分析。 **严重性等级区间：** `0–20 干净 · 21–40 低危 · 41–60 中危 · 61–80 高危 · 81–100 严重` ## 🛠️ 技术栈 | 层级 | 技术 | |---|---| | 运行时 | Node.js 18+ · Express | | 数据库 | SQLite (better-sqlite3) | | 邮件 (实时) | IMAP — `imapflow` + `mailparser` | | 前端 | 原生 HTML/CSS/JS + Chart.js (无构建步骤) | | 实时 | Server-Sent Events | ## 📚 文档 - 📘 **[完整指南 (PDF)](docs/MailGuard-Pro-Complete-Guide.pdf)** — 包含分步说明、示例、配置、API 和词汇表的各项功能详解。 - 📄 **[技术报告](docs/MailGuard-Pro-Technical-Report.docx)** — 架构与设计的深度解析。 ## ✅ 验证 | 测试 | 结果 | |---|---| | 合法邮件语料库 — 高危/严重误报 | **0%** (目标 < 5%) | | 确认的 PayPal 钓鱼样本 | **100 / 严重** | | 合法的 Google 提醒 | **0 / 干净** | | Brand Recon (`paypal.com`) | 约 10 秒内发现 **74** 个活跃相似域名 | | DNS sinkhole | 被封锁域名 → sinkhole IP | | 邮件身份验证强制执行 | 欺骗 → 拒绝，合法 → 投递 | ## 🗺️ 路线图 - **AI 分析层** — 通过预留的 `aiVerdict` hook 接入基于 Claude 的分析器，以强化最棘手的场景（例如商业电子邮件妥协）。基于规则的引擎仍保留为可解释的基线。 - 面向生产环境加固的仪表板身份验证和严格的 CSP。 - 针对受保护域名的定期的安全态势监控。 ## ⚠️ 免责声明 MailGuard Pro 是一款**防御性安全**工具，旨在授权情况下用于您自己的邮箱和基础设施。请结合您所在组织的政策，负责任地配置 `PROTECTED_DOMAINS`、威胁情报源和 DNS sinkhole。 ## 📄 许可证 基于 **MIT License** 发布 — 详见 [LICENSE](LICENSE)。

标签：DNS Sinkhole, GNU通用公共许可证, Node.js, SOC分析, 反钓鱼, 威胁情报, 开发者工具, 网络安全, 自定义脚本, 隐私保护