abdulqayyum43/mailguard
GitHub: abdulqayyum43/mailguard
MailGuard 是一个自托管的邮件安全分析 API，通过全面检测 SPF、DKIM、DMARC 等协议配置来评估域名的防伪造能力并生成合规报告。
Stars: 1 | Forks: 0
# MailGuard
**即时邮件安全情报 —— 通过一次 API 调用获取 SPF, DKIM, DMARC, MTA-STS, BIMI, 黑名单和欺骗性分析**
MailGuard 是一个自托管的邮件安全平台，可分析域名的完整身份验证和可交付性设置。它能为您提供可操作的安全评分（A–F），标记出每一项配置错误，并生成符合 PCI-DSS, SOC 2 和 ISO 27001 审计要求的 PDF 报告。只需一个 POST 请求，就能告诉您某个域名是否会被伪造 —— 以及具体的修复方法。
## 为什么选择 MailGuard?
仅检查 SPF 并不能告诉您您的域名是否免受欺骗。一条有效的 SPF 记录如果配合了 `p=none` 的 DMARC，意味着攻击者仍然可以自由地冒充您。缺失 MTA-STS 策略意味着您的邮件可能在传输过程中被降级。MailGuard 会同时运行所有 10 项检查，并为您提供最关键的指标：这个域名是否可被伪造，以及为什么？
## 它的功能
```
Request → FastAPI → API Key Auth → Rate Limiter
↓
analyze(domain)
↓
┌──────────────────────────────────────────┐
│ Parallel DNS + Security Checks │
│ SPF │ DKIM │ DMARC │ MTA-STS │
│ BIMI │ MX Records │ STARTTLS │
│ DANE/TLSA │ Blacklists │ Spoofability │
└──────────────────────────────────────────┘
↓
Grade (A+ → F) + Spoofable: true/false
Issues + Recommendations
```
## 快速开始
```
pip install -r requirements.txt
cp .env.example .env
uvicorn main:app --reload --port 8004
```
立即分析域名：
```
curl -X POST http://localhost:8004/analyze \
-H "X-API-Key: mailg-free-your-key-here" \
-H "Content-Type: application/json" \
-d '{"domain": "yourdomain.com"}'
```
交互式文档位于 **http://localhost:8004/docs**
## 您将获得什么
| 功能 | 描述 |
|---|---|
| 📋 **SPF** | 记录存在性、语法、机制分析、`+all` 检测 |
| 🔑 **DKIM** | 密钥存在性、密钥长度、算法强度 |
| 🛡️ **DMARC** | 策略严格度（`none`/`quarantine`/`reject`）、报告配置 |
| 🔒 **MTA-STS** | 严格传输安全策略的存在性和模式 |
| 🏷️ **BIMI** | 品牌指示器记录和 VMC 证书检查 |
| 📬 **MX 记录** | 邮件服务器的存在性和配置 |
| 🔐 **STARTTLS** | 邮件服务器上的机会性加密支持 |
| 🌐 **DANE / TLSA** | 基于DNS的命名实体身份验证 |
| 🚫 **黑名单** | 跨主要拦截列表的多 RBL 检查 |
| 🎯 **欺骗性评分** | 基于所有综合结果的总体冒充风险 |
## 评分系统
| 等级 | 分数 | 含义 |
|---|---|---|
| A+ | 96–100 | 所有最佳实践均已到位 —— 域名无法被伪造 |
| A | 90–95 | 非常强大的配置 |
| B | 75–89 | 良好，有轻微缺失 |
| C | 60–74 | 存在中度问题 —— 有被欺骗的风险 |
| D | 40–59 | 严重的配置错误 |
| F | 0–39 | 致命错误 —— 域名可被伪造 |
## 检查内容
| 检查项 | 描述 |
|---|---|
| **SPF** | 记录存在性、语法、机制分析、`+all` 检测 |
| **DKIM** | 密钥存在性、密钥长度、算法强度 |
| **DMARC** | 策略严格度（`none` / `quarantine` / `reject`）、报告配置 |
| **MTA-STS** | 严格传输安全策略的存在性和有效性 |
| **BIMI** | 品牌指示器记录和 VMC 证书 |
| **MX 记录** | 邮件服务器的存在性和配置 |
| **STARTTLS** | 邮件服务器上的机会性加密支持 |
| **DANE / TLSA** | 基于DNS的命名实体身份验证 |
| **黑名单** | 跨主要拦截列表的多 RBL 检查 |
| **欺骗性** | 基于综合结果的总体被伪造风险 |
## API 参考
### `POST /analyze` — 分析域名
**Headers:** `X-API-Key: your-key` | `Content-Type: application/json`
**请求：**
```
{"domain": "yourdomain.com"}
```
**响应：**
```
{
"domain": "yourdomain.com",
"grade": "B",
"score": 78,
"issue_count": 2,
"issues": [
{
"severity": "high",
"check": "DMARC",
"message": "DMARC policy is set to 'none' — emails are not rejected or quarantined",
"recommendation": "Change p=none to p=quarantine or p=reject to enforce DMARC"
},
{
"severity": "info",
"check": "BIMI",
"message": "No BIMI record found",
"recommendation": "Add a BIMI record to display your logo in supported email clients"
}
],
"spf": {"record": "v=spf1 include:_spf.yourdomain.com -all", "valid": true, "all_mechanism": "-all"},
"dmarc": {"record": "v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com", "policy": "none", "valid": true},
"dkim": {"selectors_found": ["mail"], "valid": true},
"mta_sts": {"policy_found": true, "mode": "enforce"},
"blacklisted": false,
"spoofable": true
}
```
### `POST /analyze/bulk` — 批量域名扫描 (Pro)
```
{"domains": ["yourdomain.com", "clientdomain.com", "example.org"]}
```
### `POST /monitor` — 持续监控 (Pro)
```
{
"domain": "yourdomain.com",
"check_interval_hours": 24,
"alert_on_grade_drop": true,
"slack_webhook": "https://hooks.slack.com/services/..."
}
```
### `POST /report/remediation` — PDF 修复指南 (Free+)
### `POST /report/compliance` — PDF 合规报告 (Pro) — PCI-DSS, SOC 2, ISO 27001
```
curl -X POST http://localhost:8004/report/compliance \
-H "X-API-Key: your-pro-key" \
-H "Content-Type: application/json" \
-d '{"domain": "yourdomain.com", "framework": "pci-dss"}' \
--output compliance-report.pdf
```
### `GET /history` — 每个 API key 的扫描历史
### `GET /usage` — 扫描计数、评分分布、使用统计
## API 级别
| Endpoint | Free | Pro | Enterprise |
|---|---|---|---|
| `/analyze` | ✅ | ✅ | ✅ |
| `/analyze/bulk` | ❌ | ✅ | ✅ |
| `/report/remediation` | ✅ | ✅ | ✅ |
| `/report/compliance` | ❌ | ✅ | ✅ |
| `/monitor` | ❌ | ✅ | ✅ |
| `/schedule` | ❌ | ✅ | ✅ |
| 速率限制 | 10次/分钟 | 60次/分钟 | 无限制 |
## 配置
| 变量 | 描述 |
|---|---|
| `ADMIN_SECRET` | 管理 endpoint 密钥 |
| `INITIAL_API_KEYS` | 逗号分隔的预加载 API key |
| `DATA_DIR` | 持久化存储路径 (默认: `./data`) |
| `SCAN_TIMEOUT` | 每个域名的扫描超时时间（秒）(默认: `15`) |
| `STRIPE_SECRET_KEY` | 启用 Stripe 计费 (可选) |
| `TOYYIBPAY_SECRET_KEY` | 启用 ToyyibPay 计费 —— 马来西亚 (可选) |
## 项目结构
```
mailguard/
├── main.py # FastAPI app & all routes
├── config.py # Settings (from .env)
├── auth.py # API key management
├── models.py # Pydantic schemas
├── rate_limiter.py # SlowAPI configuration
├── analytics.py # Per-key usage tracking
├── scan_history.py # Persistent scan history store
├── monitoring.py # Background monitoring service
├── scheduler.py # Scheduled scan service
├── portfolio.py # Portfolio management
├── webhook_manager.py # Webhook delivery and logging
├── alerts.py # Alert delivery (Slack, PagerDuty, email)
├── pdf_report.py # Security PDF report generator
├── remediation_report.py # Remediation guide PDF generator
├── compliance_report.py # PCI-DSS/SOC2/ISO27001 PDF generator
├── analyzer/
│ └── scorer.py # Core email security analysis engine
├── stripe_billing.py # Stripe integration
├── toyyibpay_billing.py # ToyyibPay (Malaysia) integration
├── static/ # Frontend dashboard
├── Dockerfile
└── docker-compose.yml
```
## 使用 Docker 运行
```
docker compose up -d
```
由 **Abdul Quyyam** 构建 · MIT License
标签：API服务, AV绕过, DKIM, DMARC, FastAPI, SPF, 请求拦截, 逆向工具, 邮件安全, 配置审计