Parse Dmarc

🚀 Parse DMARC

Parse DMARC 可以帮助你监控代表你的域名发送电子邮件的对象，检测仿冒行为并阻止网络钓鱼。它能自动从你的收件箱中提取 DMARC 报告，解析这些报告，并在美观的仪表板中展示所有信息。

🚀 快速开始

步骤 1：设置 DNS 以接收 DMARC 报告

这是最重要的一步！如果不进行此设置，你将无法收到任何可分析的报告。

在你的域名 DNS 中添加一条 DMARC TXT 记录：

名称：_dmarc.yourdomain.com
类型：TXT
值：v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com

含义解释：

• p=none - 仅进行监控（暂不阻止电子邮件）
• rua=mailto:dmarc@yourdomain.com - 将聚合报告发送到该电子邮件地址

重要提示：请将 dmarc@yourdomain.com 替换为你实际控制的电子邮件收件箱。这是 Gmail、Outlook、Yahoo 等将发送 DMARC 报告的地方。

DNS 设置示例：

• Cloudflare：DNS > 添加记录 > 类型：TXT，名称：_dmarc，内容：v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com
• Google Domains：DNS > 自定义记录 > TXT，名称：_dmarc，数据：v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com
• AWS Route53：创建记录 > 类型：TXT，名称：_dmarc.yourdomain.com，值："v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com"

报告通常会在 24 - 48 小时内开始送达。

步骤 2：使用 Docker 运行 Parse DMARC

运行容器：

docker run -d \
  --name parse-dmarc \
  -p 8080:8080 \
  -e IMAP_HOST=imap.gmail.com \
  -e IMAP_PORT=993 \
  -e IMAP_USERNAME=your-email@gmail.com \
  -e IMAP_PASSWORD=your-app-password \
  -v parse-dmarc:/data \
  meysam81/parse-dmarc

Gmail 用户注意：你需要使用 应用密码，而不是常规的 Gmail 密码。

访问仪表板：在浏览器中打开 http://localhost:8080。

✨ 主要特性

• 📧 自动从任何 IMAP 收件箱（Gmail、Outlook 等）获取报告
• 📊 美观的仪表板，提供实时统计信息
• 🔍 准确查看以你的域名发送电子邮件的对象
• 🔧 内置 DNS 记录生成器，便于轻松设置 DMARC
• 📦 单二进制文件 - 无需安装数据库，无需复杂设置
• 🚀 仅 14MB 的小型 Docker 镜像
• 🔒 支持安全的 TLS
• 🌙 支持暗黑模式

📦 安装指南

Homebrew（macOS/Linux）

brew tap meysam81/tap
brew install parse-dmarc

Docker

docker pull meysam81/parse-dmarc

二进制文件下载

从 发布页面 下载预构建的二进制文件。

💻 使用示例

基础用法

当 DMARC 报告开始送达且 Parse DMARC 处理它们后，你的仪表板将显示以下内容：

• 总邮件数：分析所有报告中的邮件总数
• DMARC 合规率：（SPF/DKIM 通过率）
• 主要发送源：（发送你域名邮件的 IP 地址和组织）
• 认证结果：（哪些邮件通过/未通过 SPF 和 DKIM 认证）
• 策略操作：（接收服务器如何处理你的电子邮件）

这有助于你：

• 验证合法电子邮件服务是否正确配置
• 检测未经授权使用你域名的行为
• 逐步从监控（p=none）过渡到强制执行（p=quarantine 或 p=reject）

📚 详细文档

配置选项

常见提供商的 IMAP 设置

Gmail：

{
  "host": "imap.gmail.com",
  "port": 993,
  "username": "your-email@gmail.com",
  "password": "your-app-password",
  "use_tls": true
}

需要 应用密码

Outlook/Office 365：

{
  "host": "outlook.office365.com",
  "port": 993,
  "username": "your-email@outlook.com",
  "password": "your-password",
  "use_tls": true
}

通用 IMAP：大多数提供商使用端口 993 并启用 TLS。请查看你提供商的文档。

命令行选项

# 仅获取一次并退出（适用于定时任务）
docker exec parse-dmarc ./parse-dmarc -fetch-once

# 仅提供仪表板服务（不进行获取操作）
docker exec parse-dmarc ./parse-dmarc -serve-only

# 自定义获取间隔（以秒为单位，默认 300）
docker exec parse-dmarc ./parse-dmarc -fetch-interval=600

常见问题解答

问：我没有收到任何报告，怎么回事？ 答：请按以下顺序检查：

1. 你是否在 DNS 中添加了 _dmarc TXT 记录？（使用 dig _dmarc.yourdomain.com TXT 等 DNS 检查工具）
2. 等待 24 - 48 小时 - 报告不是即时的
3. 你的域名是否正在发送/接收电子邮件？没有邮件就没有报告
4. 检查 config.json 中的 IMAP 凭证是否正确

问：我需要先设置 SPF 和 DKIM 吗？ 答：不需要！DMARC 报告将显示 SPF 和 DKIM 是否通过，这有助于你正确配置它们。

问：我的 DMARC 策略应该是什么？ 答：从 p=none（仅监控）开始。在查看报告并解决任何问题后，逐步过渡到 p=quarantine 然后 p=reject。

问：我需要多少电子邮件流量？ 答：任何数量都可以。即使是每天只有几封邮件的小域名也会收到有用的报告。

问：我可以使用 Gmail 账户接收报告吗？ 答：可以！创建一个专用的 Gmail 账户，如 dmarc@yourdomain.com，如有需要将其转发到你的个人 Gmail 账户，并使用 Gmail 的 IMAP 设置。

高级用法

从源代码构建

git clone https://github.com/meysam81/parse-dmarc.git
cd parse-dmarc
just install-deps
just build
./bin/parse-dmarc -config=config.json

Docker Compose

请参阅 了解 Docker Compose 配置。

API 端点

• GET /api/statistics - 仪表板统计信息
• GET /api/reports - 报告列表（分页）
• GET /api/reports/:id - 详细报告视图
• GET /api/top-sources - 主要发送源 IP 地址
• GET /metrics - Prometheus 指标端点

Prometheus 指标与 Grafana 集成

Parse DMARC 包含用于监控和警报的生产就绪 Prometheus 指标。指标默认启用，并在 /metrics 暴露。

可用指标

构建信息

报告处理

IMAP 连接

DMARC 统计信息

按域名/组织的指标

认证结果

HTTP 服务器

Go 运行时（内置）

还会暴露标准的 Go 运行时指标：

• go_goroutines - 协程数量
• go_memstats_* - 内存统计信息
• go_gc_* - 垃圾回收指标
• process_* - 进程指标（CPU、内存、文件描述符）

禁用指标

要禁用指标端点：

# 命令行
./parse-dmarc --metrics=false

# 环境变量
export PARSE_DMARC_METRICS=false

# Docker
docker run -e PARSE_DMARC_METRICS=false meysam81/parse-dmarc

Prometheus 配置

将 Parse DMARC 添加到你的 prometheus.yml：

scrape_configs:
  - job_name: "parse-dmarc"
    static_configs:
      - targets: ["parse-dmarc:8080"]
    scrape_interval: 30s
    metrics_path: /metrics

对于使用 ServiceMonitor（Prometheus Operator）的 Kubernetes：

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  name: parse-dmarc
  labels:
    app: parse-dmarc
spec:
  selector:
    matchLabels:
      app: parse-dmarc
  endpoints:
    - port: http
      path: /metrics
      interval: 30s

Grafana 仪表板

grafana/dashboard.json 中包含一个生产就绪的 Grafana 仪表板。

手动导入

1. 在 Grafana 中，转到 仪表板 > 导入
2. 上传 grafana/dashboard.json 或粘贴其内容
3. 选择你的 Prometheus 数据源
4. 点击 导入

自动配置（推荐用于生产环境）

# 将仪表板复制到 Grafana 仪表板目录
cp grafana/dashboard.json /var/lib/grafana/dashboards/parse-dmarc/

# 复制配置文件
cp grafana/provisioning.yaml /etc/grafana/provisioning/dashboards/parse-dmarc.yaml

# 重启 Grafana 或等待其自动更新
systemctl restart grafana-server

仪表板变量

仪表板部分

示例 Grafana 面板

合规率仪表盘：

parse_dmarc_dmarc_compliance_rate

随时间变化的邮件数：

rate(parse_dmarc_dmarc_messages_total[5m])

按域名的合规率：

parse_dmarc_dmarc_compliance_rate_by_domain

SPF/DKIM 通过率：

# SPF 通过率
parse_dmarc_dmarc_spf_results{result="pass"} / ignoring(result) sum(parse_dmarc_dmarc_spf_results) * 100

# DKIM 通过率
parse_dmarc_dmarc_dkim_results{result="pass"} / ignoring(result) sum(parse_dmarc_dmarc_dkim_results) * 100

获取成功率：

1 - (rate(parse_dmarc_reports_fetch_errors_total[1h]) / rate(parse_dmarc_reports_fetch_cycles_total[1h]))

IMAP 连接健康状况：

rate(parse_dmarc_imap_connections_total{status="success"}[5m]) /
(rate(parse_dmarc_imap_connections_total{status="success"}[5m]) + rate(parse_dmarc_imap_connections_total{status="error"}[5m]))

HTTP 请求延迟（p95）：

histogram_quantile(0.95, rate(parse_dmarc_http_request_duration_seconds_bucket[5m]))

按组织的报告数：

topk(10, parse_dmarc_dmarc_reports_by_org)

警报规则

示例 Prometheus 警报规则：

groups:
  - name: parse-dmarc
    rules:
      - alert: DMARCComplianceLow
        expr: parse_dmarc_dmarc_compliance_rate < 90
        for: 1h
        labels:
          severity: warning
        annotations:
          summary: "DMARC 合规率低于 90%"
          description: "当前合规率: {{ $value }}%"

      - alert: DMARCFetchFailures
        expr: rate(parse_dmarc_reports_fetch_errors_total[15m]) > 0
        for: 30m
        labels:
          severity: critical
        annotations:
          summary: "检测到 Parse DMARC 获取失败"
          description: "IMAP 获取操作失败"

      - alert: IMAPConnectionErrors
        expr: rate(parse_dmarc_imap_connections_total{status="error"}[5m]) > 0
        for: 10m
        labels:
          severity: warning
        annotations:
          summary: "检测到 IMAP 连接错误"
          description: "检查 IMAP 凭证和服务器连接性"

      - alert: NoRecentFetch
        expr: time() - parse_dmarc_reports_last_fetch_timestamp_seconds > 600
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "最近未获取 DMARC 报告"
          description: "上次获取是 {{ humanizeDuration $value }} 前"

Docker Compose 与 Prometheus 和 Grafana

完整的监控堆栈：

version: "3.8"

services:
  parse-dmarc:
    image: meysam81/parse-dmarc
    ports:
      - "8080:8080"
    volumes:
      - ./config.json:/app/config.json
      - ./data:/data

  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    command:
      - "--config.file=/etc/prometheus/prometheus.yml"

  grafana:
    image: grafana/grafana
    ports:
      - "3000:3000"
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin
    volumes:
      - grafana-data:/var/lib/grafana

volumes:
  grafana-data:

使用 prometheus.yml：

global:
  scrape_interval: 15s

scrape_configs:
  - job_name: "parse-dmarc"
    static_configs:
      - targets: ["parse-dmarc:8080"]

访问地址：

• Parse DMARC 仪表板：http://localhost:8080
• Prometheus：http://localhost:9090
• Grafana：http://localhost:3000（管理员账号：admin/admin）

为什么选择 Parse DMARC 而不是 ParseDMARC？

本项目受 ParseDMARC 启发，但构建得更加简单：

• 单个 14MB 二进制文件 对比 Python + Elasticsearch + Kibana 堆栈
• 内置仪表板 对比外部可视化工具
• SQLite 对比 Elasticsearch（无需 JVM）
• 零依赖 对比复杂的设置

📄 许可证

本项目采用 Apache-2.0 许可证，详情请参阅 LICENSE。

觉得这个项目有用？给仓库点个星吧！ ⭐