Khalil-secure/MailGuard_alternative

# MailGuard 🛡️ ## 这是什么？ MailGuard 是一个全栈 SaaS 平台，可实时检测钓鱼邮件。粘贴任何可疑邮件，系统会将其与 5 个全球威胁情报数据库进行交叉比对，并返回明确的判定结果：**安全 (SAFE)**、**可疑 (SUSPICIOUS)** 或 **钓鱼 (PHISHING)**。 该项目采用微服务架构构建，集成了 Google OAuth 身份验证、PostgreSQL 用户账户、HashiCorp Vault 密钥管理，并部署在 Google Cloud 上——这是一个真正的产品，而非玩具。  ## 架构 ## 架构决策 有关解释每个主要技术选门的完整 ADR，请参阅 [docs/decisions/](docs/decisions/)。 ### 容器 | 容器 | 技术栈 | 端口 | 角色 | |---|---|---|---| | `gateway` | Node.js / Express | 3000 | 身份验证、路由、速率限制 | | `ai-service` | Python / FastAPI | 8000 | AI 微服务 | | `phishing-detector` | Python / FastAPI + aiosmtpd | 8001 / 1025 | 威胁分析引擎 | | `vault` | HashiCorp Vault | 8200 | 密钥管理 | | `postgres` | PostgreSQL 15 | 5432 | 用户 + 扫描历史记录 | ## 功能 ### 身份验证 - **Google OAuth 2.0** —— 一键登录 - **JWT token** —— 7天有效期，无状态 - **PostgreSQL 用户存储** —— 重启后数据依然保留 ### 速率限制 - 每个用户每天 **10 次免费扫描** - 通过 PostgreSQL 按每 24 小时窗口对用户进行跟踪 - 达到限制时返回带有升级提示的 `429` 响应 ### 钓鱼检测引擎 - **域名仿冒 (Typosquatting)** —— 通过 Levenshtein 距离比对 25 个以上知名品牌 (`paypa1.com → paypal.com`) - **VirusTotal** —— URL 和域名信誉（70 多个 AV 引擎） - **AlienVault OTX** —— 威胁脉动检测 - **AbuseIPDB** —— IP 滥用置信度评分 - **Google Safe Browsing** —— Google 的威胁数据库 - **SPF / DMARC** —— DNS 级别发件人验证 - 所有检查均通过 `asyncio.gather` **并行**运行 ### 密钥管理 - **HashiCorp Vault** 生产模式，采用文件存储 - 密钥在容器重启后依然保留 - 服务在运行时获取密钥 —— 磁盘上无任何密钥 - 解密密钥阈值：需要 5 把密钥中的 3 把 ### 双重接口 - **REST API** —— `POST /phishing/analyze` - **SMTP 服务器** —— 在端口 1025 接收邮件 ### 前端 - 单一粘贴框 —— 粘贴原始邮件，自动提取 headers - 即时判定，并提供每个引擎的详细细分 - 显示剩余每日扫描次数的扫描计数器 - 用于捕获潜在客户的新闻通讯注册 ## 可观测性 | 工具 | 角色 | 端口 | |------|------|------| | Prometheus | 指标收集 | 9090 | | Grafana | 仪表盘和可视化 | 3001 | | Loki | 日志聚合 | 3100 | | Promtail | 日志传送 | - | **仪表盘面板：** - 总扫描数 / 检测到的钓鱼邮件 / 触发速率限制次数 / 活跃用户 - 每分钟扫描数（实时） - 判定结果细分（甜甜圈图） - 各 API 的威胁引擎命中数 - API 响应时间 p95 - 🌱 碳足迹（每次扫描的 gCO2，基于 GCP europe-west1）   ## 技术栈 | 层级 | 技术 | |---|---| | 前端 | HTML / CSS / JS —— 部署在 Vercel | | 网关 | Node.js 20, Express, Passport, JWT, pg | | 后端服务 | Python 3.11, FastAPI, uvicorn, httpx | | SMTP 服务器 | aiosmtpd | | 密钥管理 | HashiCorp Vault（文件存储） | | 数据库 | PostgreSQL 15 | | 容器化 | Docker, Docker Compose | | 反向代理 | Nginx | | 隧道 | Cloudflare Tunnel | | 云平台 | Google Cloud Compute Engine (e2-medium, Ubuntu 22.04) | | 威胁 API | VirusTotal, AlienVault OTX, AbuseIPDB, Google Safe Browsing | ## 项目结构 ``` mailguard/ ├── docker-compose.yml ├── .env.example ├── .gitignore ├── README.md ├── frontend/ │ ├── index.html │ └── vercel.json └── services/ ├── gateway/ │ ├── index.js # Express gateway, OAuth, JWT, rate limiting │ ├── auth.js # JWT middleware │ ├── package.json │ └── Dockerfile ├── ai-service/ │ ├── main.py # FastAPI summarizer │ ├── requirements.txt │ └── Dockerfile └── phishing-detector/ ├── smtp_server.py # SMTP receiver ├── api.py # FastAPI REST endpoint ├── checks.py # All threat intelligence checks ├── vault_client.py # HashiCorp Vault secret loader ├── requirements.txt └── Dockerfile ``` ## 快速开始 ### 前置条件 - Docker Desktop - Git - API 密钥（见下文） - Google OAuth 凭证 ### 1. 克隆 ``` git clone https://github.com/khalil-secure/mailguard.git cd mailguard ``` ### 2. 环境变量 ``` cp .env.example .env ``` 填写 `.env`： ``` # 威胁情报 VIRUSTOTAL_API_KEY= ABUSEIPDB_API_KEY= ALIENVAULT_API_KEY= GOOGLE_SAFEBROWSING_API_KEY= HUGGINGFACE_API_KEY= # Auth GOOGLE_CLIENT_ID= GOOGLE_CLIENT_SECRET= GOOGLE_CALLBACK_URL= JWT_SECRET= SESSION_SECRET= # 数据库 DATABASE_URL=postgresql: # Vault VAULT_TOKEN= VAULT_ADDR= ``` ### 3. 运行 ``` docker compose up -d ``` ### 4. 初始化 Vault ``` # 解封 Vault（仅首次） docker exec -e VAULT_ADDR='http://127.0.0.1:8200' mailguard-vault vault operator init # 使用 5 把密钥中的 3 把解封 docker exec -e VAULT_ADDR='http://127.0.0.1:8200' mailguard-vault vault operator unseal KEY1 docker exec -e VAULT_ADDR='http://127.0.0.1:8200' mailguard-vault vault operator unseal KEY2 docker exec -e VAULT_ADDR='http://127.0.0.1:8200' mailguard-vault vault operator unseal KEY3 # 加载 secrets docker exec -e VAULT_ADDR='http://127.0.0.1:8200' -e VAULT_TOKEN='YOUR_ROOT_TOKEN' \ mailguard-vault vault kv put mailguard/api-keys \ VIRUSTOTAL_API_KEY=... \ ABUSEIPDB_API_KEY=... \ ALIENVAULT_API_KEY=... \ GOOGLE_SAFEBROWSING_API_KEY=... \ HUGGINGFACE_API_KEY=... ``` ## API 参考 ### 身份验证 ``` GET /auth/google # Redirect to Google OAuth GET /auth/google/callback # OAuth callback GET /auth/me # Get current user + scan count (JWT required) ``` ### 钓鱼分析 ``` POST /phishing/analyze # Requires Bearer token ``` **请求：** ``` { "sender": "security@paypa1.com", "subject": "Urgent: Verify your account", "body": "Click here: http://suspicious.ru/login" } ``` **响应：** ``` { "verdict": "PHISHING", "checks": [ { "verdict": "PHISHING", "reason": "'paypa1.com' looks like 'paypal.com' (distance: 1)" }, { "source": "virustotal", "malicious": 10, "suspicious": 1, "verdict": "PHISHING" }, { "source": "safebrowsing", "verdict": "PHISHING", "flagged_urls": ["..."] } ], "sender_domain": "paypa1.com", "dns_checks": { "spf": true, "dmarc": false } } ``` **速率限制响应 (429)：** ``` { "error": "Daily limit reached", "message": "You have used all 10 free scans for today. Upgrade to Pro for unlimited scans.", "scans_used": 10, "limit": 10 } ``` ## API 密钥 | 服务 | 免费层级 | 链接 | |---|---|---| | VirusTotal | 500 请求/天 | https://virustotal.com | | AbuseIPDB | 1000 请求/天 | https://abuseipdb.com | | AlienVault OTX | 无限制 | https://otx.alienvault.com | | Google Safe Browsing | 免费 | https://developers.google.com/safe-browsing | | HuggingFace | 免费层级 | https://huggingface.co | ## 路线图 - [ ] Stripe 集成 —— 用于无限扫描的 Pro 计划 - [ ] 浏览器扩展 —— 实时标记 Gmail/Outlook 中的邮件 - [ ] 文件/附件扫描 —— VirusTotal 哈希查找 - [ ] 自定义域名 + SSL (Let's Encrypt) - [ ] 管理仪表盘 —— 使用分析 - [ ] Webhook API —— 与邮件提供商集成 - [ ] 移动应用 ## 背景故事 整个平台是在一次连续的长时间开发中构建的——每一个服务在构建下一个之前都经过了运行验证，每一个问题都在生产环境中进行了调试。 技术栈包括微服务、OAuth、JWT、密钥管理、威胁情报 API、Docker 编排、云部署以及真正的 SaaS 商业模式。 ## 许可证 MIT

标签：GNU通用公共许可证, MITM代理, Node.js, Python, SaaS平台, 后端开发, 威胁情报, 开发者工具, 微服务架构, 无后门, 测试用例, 版权保护, 网络测绘, 自定义请求头, 请求拦截, 逆向工具, 钓鱼检测