eR4Ys/DMARC-Insight

# DMARC-Insight    

## 核心理念 DMARC-Insight 基于一个简单且不容妥协的前提：**纯粹的系统性问题解决**。没有臃肿的配置，没有不必要的摩擦。你提供一个 IMAP 邮箱，管道处理原始数据，发送一份精美的情报报告，完成整个循环。 ## 核心能力 - 通过 IMAP 自主摄取 DMARC 报告 - 智能 XML 解析与威胁分析 - IP 地理定位丰富与分类 - 可读性强的安全洞察与 KPI - 自动化 HTML 报告生成与 SMTP 投递 - Docker 就绪、可自托管的架构 ## 处理管道 DMARC-Insight 充当自主智能代理。一旦配置完成，应用程序会直接连接到指定的 IMAP 邮箱，扫描来自邮件服务商（Google、Microsoft、Yahoo 等）的新 DMARC 聚合报告。它提取附件中的 XML 文件，解压缩后通过精密的解析器进行处理。随后原始数据被送入分析引擎，评估域名健康状况、交叉引用 IP 地址以识别地理威胁，并结构化分析结果。最后，这些结构化数据被编译为高可视化的 HTML 模板，通过 SMTP 直接发送给安全团队。 该架构依赖于企业级、确定性的 **5 阶段管道**： | 阶段 | 阶段名称 | 执行细节 | | :----- | :------------- | :-------------------------------------------------------------- | | **01.** | **获取** | 智能 IMAP 附件提取与解压缩。 | | **02.** | **解析** | 将原始 XML 精确解析为结构化 JSON。 | | **03.** | **分析** | 域名健康评估、IP 地理定位丰富与威胁分类。 | | **04.** | **报告** | 基于 Handlebars 的 HTML 模板编译，包含 KPI 与洞察。 | | **05.** | **投递** | 通过 SMTP 安全投递给安全团队。 | ## 报告分析 生成的报告旨在即时呈现关键威胁。分析引擎产出多项核心洞察： - **健康评分与 KPI** — 评估 DMARC 合规性的综合指标，对比授权与非授权邮件量。 - **地理威胁** — 识别映射到特定国家/地区和 ISP 的恶意或未授权邮件来源。 - **安全告警** — 高优先级警告，指示严重配置错误、部分执行或主动欺骗尝试。 - **流量分析** — 将复杂的 XML 失败信息翻译为通俗易懂的语句（例如 `AUTHORIZED`、`FAILED – Config Issue`），清晰展示特定邮件流被拒绝的原因。 - **趋势洞察** — 历史对比，突出域名安全态势随时间的改善或恶化。 ## 技术栈 专为韧性构建。毫不妥协。 **核心框架** - **NestJS** — 架构基础，提供模块化、依赖注入与调度能力。 - **TypeScript** — 贯穿整个代码库的端到端类型安全。 **数据持久化与 ORM** - **better-sqlite3 / sql.js** — 高性能、同步数据持久化。 - **TypeORM** — 健壮的实体映射与数据库交互。 **网络与邮件** - **imapflow** — 现代、基于 Promise 的 IMAP 客户端，高效获取邮件。 - **nodemailer** — 用于报告投递的安全 SMTP 传输。 - **axios** — 灵活的 HTTP 客户端，用于外部 API 集成（GeoIP 等）。 **处理与模板** - **fast-xml-parser** — 快速且安全的 XML 到 JSON 转换。 - **fflate** — 高性能 ZIP/GZIP 解压。 - **Handlebars** — 语义化且动态的 HTML 模板编译。 **安全与验证** - **Joi / class-validator** — 严格的环境与运行时模式验证。 - **Helmet** — 加固 HTTP 头。 **可观测性** - **Winston** — 企业级结构化日志。 - **Terminus** — 健康检查与优雅关闭编排。 ## API 参考 交互接口刻意保持精简。 | 方法 | 端点 | 操作 | | :------ | :----------------- | :--------------------------------------------- | | `POST` | `/pipeline/run` | 手动触发完整处理管道。 | | `GET` | `/pipeline/status` | 获取当前指标与管道状态。 | | `GET` | `/health` | Terminus 存活/就绪探针。 | ## 环境变量 | 变量 | 必填 | 描述 | | :------------------ | :--: | :---------------------------------------------------------------------------- | | `API_KEY` | ✅ | 用于保护特定端点的 API 密钥。必须以 `di_live_` 开头。 | | `IMAP_HOST` | ✅ | IMAP 服务器主机名（例如 `imap.gmail.com`）。 | | `IMAP_PORT` | ✅ | IMAP 端口，SSL 通常为 `993`。 | | `IMAP_USER` | ✅ | 用于 IMAP 认证的邮箱地址。 | | `IMAP_PASS` | ✅ | IMAP 认证的密码或应用专用密码。 | | `SMTP_HOST` | ✅ | 用于报告投递的 SMTP 服务器主机名。 | | `SMTP_PORT` | ✅ | SMTP 端口（例如 STARTTLS 为 `587`，SSL 为 `465`）。 | | `SMTP_SECURE` | ✅ | 定义连接加密方式。 | | `SMTP_USER` | ✅ | 用于 SMTP 认证的邮箱地址。 | | `SMTP_PASS` | ✅ | SMTP 认证的密码或应用专用密码。 | | `REPORT_RECIPIENTS` | ✅ | 接收情报报告的邮箱地址。 | | `GEOIP_ENABLED` | — | 设为 `true` 可通过 ip-api.com 对 IP 进行国家/ISP 数据丰富。 | | `CRON_SCHEDULE` | — | 管道调度的 Cron 表达式。默认为 `0 * * * *`（每小时）。 | | `PORT` | — | API 服务器的 HTTP 端口。默认为 `4100`。 | ## 安装说明 ### 🐳 即时部署（Docker） 部署 DMARC-Insight 的主要且无障碍方式。 **第 1 步：克隆与配置** ``` git clone https://github.com/eR4Ys/DMARC-Insight.git cd DMARC-Insight cp .env.example .env ``` **第 2 步：填写凭据** 打开 `.env` 文件，配置 IMAP 和 SMTP 凭据，并根据需要切换 `GEOIP_ENABLED`。 **第 3 步：启动** ``` docker compose up -d --build ``` _DMARC-Insight 现在已在后台自主运行。_ ### 🚀 独立生产环境部署 适用于不希望在 Docker 内运行的生产环境。需要 **Node.js v22 LTS** 或**更高版本**（推荐使用 LTS 版本）。 **第 1 步：克隆与干净安装** ``` git clone https://github.com/eR4Ys/DMARC-Insight.git cd DMARC-Insight npm ci ``` **第 2 步：填写凭据** 打开 `.env` 文件，配置 IMAP 和 SMTP 凭据，并根据需要切换 `GEOIP_ENABLED`。 ``` cp .env.example .env ``` **第 3 步：构建与初始化** ``` # 将 TypeScript 编译为生产就绪的 JavaScript npm run build # 初始化 SQLite 数据库架构 npm run migration:run ``` **第 4 步：启动** ``` npm run start:prod ``` ### 🛆 手动集成与开发模式 适用于希望直接运行 NestJS 应用的开发者。需要 **Node.js v22 LTS** 或**更高版本**（推荐使用 LTS 版本）。 **第 1 步：克隆与安装** ``` git clone https://github.com/eR4Ys/DMARC-Insight.git cd DMARC-Insight npm install ``` **第 2 步：填写凭据** 打开 `.env` 文件，配置 IMAP 和 SMTP 凭据，并根据需要切换 `GEOIP_ENABLED`。 ``` cp .env.example .env ``` **第 3 步：初始化数据库** ``` # 初始化 SQLite 数据库架构 npm run migration:run ``` **第 4 步：以开发模式启动** ``` # 以 watch/开发模式启动 NestJS 服务器 npm run start:dev ``` ## 路线图 **[ MVP 之后 ]** - [ ] 分布式任务队列（BullMQ），用于高容量邮箱。 - [ ] Webhook 通知（Slack / Discord）。

标签：CSP, DKIM, DMARC, Docker, HTML报告, IMAP报告分析, NestJS, PB级数据处理, SMTP交付, SPF, TypeScript, XML解析, XML 请求, 地理IP富集, 域名健康监控, 威胁情报, 安全产品, 安全优化, 安全分析引擎, 安全功能, 安全可视化, 安全应用, 安全开发, 安全性能, 安全情报代理, 安全技术, 安全报告, 安全接口, 安全控制, 安全插件, 安全更新, 安全服务, 安全机制, 安全架构, 安全标准, 安全模块, 安全模型, 安全洞察, 安全流程, 安全测试, 安全特性, 安全策略, 安全管道, 安全系统, 安全组件, 安全维护, 安全规范, 安全解决方案, 安全设计, 安全质量, 安全软件, 安全运维, 安全运营, 安全部署, 安全防御评估, 安全集成, 开发者工具, 开源, 扫描框架, 提示词设计, 攻击性安全, 电子邮件安全, 网络安全, 网络安全KPI, 自动化安全报告, 自动化攻击, 自托管, 请求拦截, 邮件安全分析, 邮件认证, 隐私保护, 零配置