annabellevibecodes/DMARCReporter

# DMARC Reporter 一个用于解析、存储和可视化 DMARC 聚合报告的 Web 应用程序。报告可以手动上传，也可以自动从 IMAP 邮箱中获取。 ## 功能 - 解析 DMARC 聚合报告 XML 文件（`.xml`、`.xml.gz`、`.gz`、`.zip`）和原始电子邮件文件（`.eml`） - 直接从 IMAP 邮箱获取报告；已处理的邮件会被移动到可配置的子文件夹中 - 仪表盘包含通过/失败统计数据、失败模式、主要失败来源以及每周趋势图表 - 三种 UI 主题 —— **Goth**（终端）、**Pink**（Y2K 魅力）、**Blue**（报纸）—— 可随时切换，并通过 cookie 持久化保存 - 域名和报告详情页上的 DKIM 选择器统计信息 - 支持导出 CSV、XLSX、PDF 和 DOCX 格式的管理报告 - 浏览带有可排序列标题的报告、域名和源 IP - 按域名和日期范围过滤报告；按 IP、envelope-from、disposition 和最小消息数（滑块）过滤来源 - 所有列表页均提供报告周期选择器 —— 所有时间、2 年、1 年、6/3 个月、上个月、30/14/7/3/2 天、过去 24 小时 - 支持配置用户名和密码的 HTTP Basic Auth - 针对上传和 IMAP 获取端点的速率限制 - SQLite 存储 —— 无需外部数据库 ## 要求 - Go 1.22 或更高版本 无需 C 编译器。SQLite 驱动程序 (`modernc.org/sqlite`) 是纯 Go 实现的。 ## 构建 ``` git clone cd DMARCReporter go build -o dmarcreporter . ``` 生成的 `dmarcreporter` 二进制文件是自包含的，没有运行时依赖项。 ## 运行 ### 不使用 IMAP（仅限文件上传） ``` ./dmarcreporter ``` 服务器默认在 `http://localhost:8080` 上启动。 ### 使用 IMAP ``` IMAP_HOST=mail.example.com \ IMAP_USER=dmarc@example.com \ IMAP_PASS=secret \ ./dmarcreporter ``` 配置 IMAP 后，导航栏中会出现一个 **Fetch IMAP** 按钮。点击它会从配置的邮箱中获取所有未读邮件，提取所有 DMARC 报告附件，将其导入，并将已处理的邮件移动到 `INBOX.Processed`（可配置）。 ## 配置 所有配置均通过环境变量进行。每个变量都有一个合理的默认值。 | 变量 | 默认值 | 描述 | |----------|---------|-------------| | `PORT` | `8080` | 要监听的 HTTP 端口 | | `DB_PATH` | `dmarc.db` | SQLite 数据库文件的路径 | | `SECURE_COOKIES` | `false` | 在通过 HTTPS 提供服务时设置为 `true`，以启用 cookie 的 `Secure` 标志和 HSTS | | `DEBUG` | `false` | 设置为 `true` 可向 stdout 和 syslog 输出详细的调试日志 | | `AUTH_USER` | `admin` | HTTP Basic Auth 用户名 | | `AUTH_PASSWORD` | _（必填）_ | HTTP Basic Auth 密码。除非设置此项，否则应用程序将拒绝启动。 | | `AUTH_DISABLED` | `false` | 设置为 `true` 可在没有身份验证的情况下运行。**仅供开发使用 —— 切勿在生产环境中使用。** | | `HSTS_ENABLED` | `false` | 设置为 `true` 以发送 `Strict-Transport-Security` 头。每当应用程序通过 HTTPS 提供服务时都应启用此项。 | | `UPLOAD_RATE_MAX` | `20` | 每个 IP 每分钟的最大文件上传次数（设为 0 可禁用） | | `FETCH_RATE_MAX` | `3` | 每个 IP 每 5 分钟的最大 IMAP 获取请求次数（设为 0 可禁用） | | `IMAP_HOST` | _（未设置）_ | IMAP 服务器主机名。未设置时禁用 IMAP。 | | `IMAP_PORT` | `993` | IMAP 服务器端口 | | `IMAP_USER` | _（未设置）_ | IMAP 用户名 | | `IMAP_PASS` | _（未设置）_ | IMAP 密码 | | `IMAP_MAILBOX` | `INBOX` | 用于获取报告的邮箱 | | `IMAP_PROCESSED_MAILBOX` | `INBOX.Processed` | 用于移动已处理邮件的目标邮箱 | | `IMAP_TLS` | `true` | 使用 TLS。仅在本地测试时设置为 `false`。 | ## 对互联网开放 如果您希望将此 Web 应用程序公开访问，我们建议使用带有预身份验证的反向代理，以实现通过互联网的安全访问。 ## 用法 ### 手动上传报告 导航至 **Upload** 并选择一个或多个报告文件。支持的格式： - `.xml` —— 纯 DMARC 聚合报告 XML - `.xml.gz` / `.gz` —— gzip 压缩的 XML - `.xml.zip` / `.zip` —— zip 归档的 XML - `.eml` —— 原始电子邮件文件；自动提取 DMARC 报告附件 重新上传已经导入的报告是安全的 —— 会检测到重复项并静默跳过。 ### 从 IMAP 获取 点击导航栏中的 **Fetch IMAP**。应用程序将： 1. 通过 TLS 连接到配置的 IMAP 服务器 2. 搜索 `IMAP_MAILBOX` 中的未读邮件 3. 提取所有 DMARC 报告附件 4. 解析并将其导入数据库 5. 将每封已处理的邮件移动到 `IMAP_PROCESSED_MAILBOX` 如果该子文件夹不存在，则会自动创建。 ### 查看数据 | 页面 | URL | 描述 | |------|-----|-------------| | 仪表盘 | `/` | 汇总统计数据和每周通过/失败趋势图表 | | 报告 | `/reports` | 所有导入的报告，可按域名和日期过滤 | | 报告详情 | `/reports/:id` | 单个报告，包含按 IP 划分的记录明细 | | 域名 | `/domains` | 所有域名及其汇总消息计数 | | 域名详情 | `/domains/:domain` | 所有报告中特定域名的记录 | | 来源 | `/sources` | 所有源 IP，可按周期、envelope-from、IP 和最小消息数过滤 | | 来源详情 | `/sources/:ip` | 所有报告中特定 IP 的记录 | | 导出 | `/export` | 管理报告下载（CSV、XLSX、PDF、DOCX）；可选 `?domain=` 过滤器 | `/api/stats?days=90` 上的 JSON 端点返回用于编程使用的趋势数据。 ### 导出管理报告 在导航栏中导航至 **Export**。选择一个域名（或留空以选择所有域名）和一种格式： | 格式 | 描述 | |--------|-------------| | CSV | 扁平化的电子表格，每条 DMARC 记录占一行 | | XLSX | Excel 工作簿 | | PDF | 格式化的报告文档 | | DOCX | Word 兼容文档 | 下载的文件命名为 `dmarc-report--.`。 ### 切换主题 点击导航栏中的主题选择器（Pink / Blue / Goth）。所选内容会保存在 `ui_theme` cookie 中，并在不同会话之间持久保留。默认主题为 **Goth**。 ## 开发 直接运行而无需构建： ``` go run . ``` 运行测试： ``` go test ./... ``` 数据库文件会在首次运行时自动创建。要从头开始，请删除 `dmarc.db`。 ## 审计日志 所有导入事件都会写入 syslog（`facility=DAEMON`，标签 `dmarcreporter`）。如果本地 syslog 守护进程不可用，相同的事件将被写入 stderr。 记录的事件： | 事件 | 严重程度 | 字段 | |-------|----------|--------| | 报告已导入 | INFO | `source`、`org`、`domain`、`report_id`、`records` | | 报告重复（已跳过） | INFO | `source`、`org`、`report_id` | | 报告解析失败 | WARNING | `source`（仅文件名，无内部细节） | | IMAP 获取已开始 | INFO | `mailbox` | | IMAP 获取已完成 | INFO | `mailbox`、`imported` | | IMAP 获取失败 | ERROR | `mailbox` | 在 macOS 上，使用以下命令查看实时审计事件： ``` log stream --predicate 'senderImagePath contains "dmarcreporter"' ``` 在 Linux (journald) 上： ``` journalctl -t dmarcreporter -f ``` 在 Linux (syslog 文件) 上： ``` grep dmarcreporter /var/log/syslog ``` ## 网络通信 下表列出了应用程序建立或接受的每一个连接。使用它来为运行 DMARC Reporter 的主机配置防火墙规则。 ### 入站 | 端口 | 协议 | 方向 | 目的 | 是否必需 | |------|----------|-----------|---------|----------| | `8080` ¹ | TCP | → 服务器 | Web UI 和 API —— 浏览器或反向代理到应用程序 | 始终需要 | ¹ 可通过 `PORT` 环境变量进行配置。 ### 出站 | 端口 | 协议 | 方向 | 目的 | 是否必需 | |------|----------|-----------|---------|----------| | `993` ² | TCP | 服务器 → | 基于 TLS 的 IMAP —— 从邮箱获取 DMARC 报告 | 仅当设置了 `IMAP_HOST` 时 | | `143` ² | TCP | 服务器 → | 不带 TLS 的 IMAP —— **仅供开发/测试**，切勿在生产环境中使用 | 仅当 `IMAP_TLS=false` 时 | | `53` | UDP + TCP | 服务器 → | DNS —— DMARC (`_dmarc.*`)、BIMI (`default._bimi.*`)、MTA-STS (`_mta-sts.*`) 记录查找，以及源 IP 的反向 DNS；使用系统解析器 | 当使用 Enrich 或域名详情功能时 | | `43` | TCP | 服务器 → | WHOIS —— 源 IP 的组织、国家/地区、网络和滥用联系人查找；连接到每个 IP 块的权威 WHOIS 服务器（ARIN、RIPE、APNIC、LACNIC、AFRINIC 等） | 当使用 Enrich 或来源详情功能时 | ² 可通过 `IMAP_PORT` 环境变量进行配置。 ## 安全说明 - 启动时需要 `AUTH_PASSWORD`；除非显式设置 `AUTH_DISABLED=true`（仅供开发），否则应用程序将拒绝启动 - 所有更改状态的 POST 请求都需要 CSRF 令牌 - Flash 消息使用 `HttpOnly`、`Secure` 和 `SameSite=Lax` cookie - 所有响应均设置了 HTTP 安全头（CSP、X-Frame-Options、Referrer-Policy、Permissions-Policy） - 上传和获取的文件在解压前限制为 10 MB；解压后的内容上限为 50 MB，以防止解压炸弹攻击 - XML 实体扩展被禁用以防止 XXE 攻击 - IMAP 明文模式（`IMAP_TLS=false`）在启动时会记录警告，应仅用于本地测试

标签：DMARC, EVTX分析, Go, Mutation, Ruby工具, SQLite, 可视化, 日志审计, 邮件安全