金大哥 - parse-dmarc MCP 详情

article

README

🚀 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

常见问题解答

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

你是否在 DNS 中添加了 _dmarc TXT 记录？（使用 dig _dmarc.yourdomain.com TXT 等 DNS 检查工具）
等待 24 - 48 小时 - 报告不是即时的
你的域名是否正在发送/接收电子邮件？没有邮件就没有报告
检查 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

请参阅 compose.yml 了解 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 暴露。

可用指标

构建信息

| 指标 | 类型 | 描述 | | ------------------------ | ----- | ----------------------------------------------- | | parse_dmarc_build_info | Gauge | 构建信息（版本、提交、构建日期） |

报告处理

| 指标 | 类型 | 描述 | | -------------------------------------------------- | --------- | ------------------------------------------- | | parse_dmarc_reports_fetched_total | Counter | 从 IMAP 获取的 DMARC 报告电子邮件总数 | | parse_dmarc_reports_parsed_total | Counter | 成功解析的 DMARC 报告总数 | | parse_dmarc_reports_stored_total | Counter | 存储在数据库中的 DMARC 报告总数 | | parse_dmarc_reports_parse_errors_total | Counter | 解析错误总数 | | parse_dmarc_reports_store_errors_total | Counter | 存储错误总数 | | parse_dmarc_reports_attachments_total | Counter | 处理的附件总数 | | parse_dmarc_reports_fetch_duration_seconds | Histogram | 获取操作的持续时间 | | parse_dmarc_reports_last_fetch_timestamp_seconds | Gauge | 最后一次成功获取的 Unix 时间戳 | | parse_dmarc_reports_fetch_cycles_total | Counter | 执行的获取周期总数 | | parse_dmarc_reports_fetch_errors_total | Counter | 获取周期错误总数 |

IMAP 连接

| 指标 | 类型 | 标签 | 描述 | | ---------------------------------------------- | --------- | ------ | ---------------------------------------- | | parse_dmarc_imap_connections_total | Counter | status | IMAP 连接尝试（成功/错误） | | parse_dmarc_imap_connection_duration_seconds | Histogram | | IMAP 连接建立持续时间 |

DMARC 统计信息

| 指标 | 类型 | 描述 | | -------------------------------------------- | ----- | --------------------------------- | | parse_dmarc_dmarc_reports_total | Gauge | 数据库中的报告总数 | | parse_dmarc_dmarc_messages_total | Gauge | 所有报告中的邮件总数 | | parse_dmarc_dmarc_compliant_messages_total | Gauge | 符合 DMARC 的邮件总数 | | parse_dmarc_dmarc_compliance_rate | Gauge | 总体合规率（0 - 100） | | parse_dmarc_dmarc_unique_source_ips | Gauge | 唯一源 IP 地址数量 | | parse_dmarc_dmarc_unique_domains | Gauge | 唯一域名数量 |

按域名/组织的指标

| 指标 | 类型 | 标签 | 描述 | | --------------------------------------------- | ----- | ----------- | ---------------------------- | | parse_dmarc_dmarc_messages_by_domain | Gauge | domain | 每个域名的邮件数 | | parse_dmarc_dmarc_compliance_rate_by_domain | Gauge | domain | 每个域名的合规率 | | parse_dmarc_dmarc_reports_by_org | Gauge | org_name | 每个组织的报告数 | | parse_dmarc_dmarc_messages_by_disposition | Gauge | disposition | 按处理类型划分的邮件数 |

认证结果

| 指标 | 类型 | 标签 | 描述 | | -------------------------------- | ----- | ------ | --------------------------------- | | parse_dmarc_dmarc_spf_results | Gauge | result | SPF 认证结果计数 | | parse_dmarc_dmarc_dkim_results | Gauge | result | DKIM 认证结果计数 |

HTTP 服务器

| 指标 | 类型 | 标签 | 描述 | | ------------------------------------------- | --------- | -------------------- | -------------------------- | | parse_dmarc_http_requests_total | Counter | method, path, status | 总 HTTP 请求数 | | parse_dmarc_http_request_duration_seconds | Histogram | method, path | HTTP 请求持续时间 | | parse_dmarc_http_requests_in_flight | Gauge | | 当前正在处理的请求数 |

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 仪表板。

手动导入

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

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

# 将仪表板复制到 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

仪表板变量

| 变量 | 用途 | | ------------ | ------------------------------ | | datasource | 要查询的 Prometheus 数据源 | | job | 按 Prometheus 作业标签过滤 | | instance | 按实例过滤 | | domain | 按监控的域名过滤 |

仪表板部分

| 部分 | 显示内容 | | ---------------------------------- | ------------------------------------------------------------------------- | | 概述 - 关键指标 | 合规率、总邮件数、报告数量、自上次获取以来的时间 | | DMARC 认证结果 | SPF/DKIM 通过率、处理细分、按域名的合规情况 | | 报告源与组织 | 主要报告组织（Google、Microsoft 等）、按域名的邮件数 | | IMAP 与获取操作 | 连接健康状况、获取周期监控、延迟热力图 | | 错误跟踪 | 解析错误、存储错误、获取失败 | | HTTP 服务器 | 请求率、延迟百分位数、错误率 | | Go 运行时 | 协程、内存使用、GC 统计、CPU 使用 |

示例 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。

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