mcisco1/email-phish-analyzer
GitHub: mcisco1/email-phish-analyzer
集成 ML 分类、NLP 分析、浏览器沙箱、YARA 扫描和威胁情报的钓鱼邮件自动化分析平台，支持 MITRE ATT&CK 映射和 STIX 2.1 导出。
Stars: 0 | Forks: 0
# PhishGuard
**自动化网络钓鱼邮件分析平台**，集成 ML 分类、NLP 内容分析、无头浏览器沙箱、YARA 扫描、多源威胁情报、MITRE ATT&CK 映射、引导式入门流程以及 Chrome 浏览器扩展。
上传 `.eml` 文件，将可疑邮件转发到共享收件箱，或者在 Gmail/Outlook 中右键单击邮件——即可获得包含置信度评分、IOC 提取、STIX 2.1 导出和可下载 PDF 文档的综合威胁报告。
## 目录
- [功能特性](#features)
- [分析流水线](#analysis-pipeline)
- [架构](#architecture)
- [快速开始](#getting-started)
- [浏览器扩展](#browser-extension)
- [邮件转发 (IMAP)](#email-forwarding-imap)
- [配置](#configuration)
- [外部 API 设置](#external-api-setup)
- [环境变量参考](#environment-variable-reference)
- [监控与维护](#monitoring--maintenance)
- [运行全部服务](#running-everything)
- [API 参考](#api-reference)
- [仪表板](#dashboard)
- [团队与组织](#team--organization)
- [通知](#notifications)
- [自定义 YARA 规则](#custom-yara-rules)
- [项目结构](#project-structure)
- [许可证](#license)
## 功能特性
- **多阶段分析流水线** — 邮件头取证、URL 沙箱、附件扫描、ML 分类、NLP 分析、浏览器沙箱、YARA 规则、威胁情报源
- **引导式入门** — 分步向导，包含示例邮件分析和交互式报告演练，提供安全术语的通俗解释
- **SOC 仪表板** — 带渐变填充的面积图、威胁速度 KPI、时间段选择器 (7d/30d/90d)、SOC 叙述性摘要、快捷操作按钮
- **浏览器扩展** — Chrome Manifest V3 扩展，支持右键菜单分析、Gmail 和 Outlook Web 工具栏按钮注入、包含最近结果的弹出窗口、徽章通知
- **邮件转发** — IMAP 收件箱轮询，自动分析转发的可疑邮件并自动回复结果
- **团队管理** — 具有角色（所有者/管理员/成员）的组织、每位成员的分析统计、团队活动源、团队 CSV 导出
- **通知** — 邮件警报、Slack webhooks、应用内通知、可配置阈值、每周摘要报告、测试通知按钮
- **专业 PDF 报告** — 带品牌标识的封面页、面向管理层的执行摘要、风险可视化条、建议措施、完整技术发现、Inter + JetBrains Mono 字体
- **导出格式** — IOC JSON、STIX 2.1、PDF 报告、CSV 批量导出
- **身份验证** — OAuth 2.0 (Google, Microsoft)、带 bcrypt 的本地认证、JWT API 令牌、RBAC (admin/analyst/viewer)
## 分析流水线
PhishGuard 通过多阶段流水线处理每封邮件。每个阶段独立运行且具有容错性——如果某个服务不可用，其余阶段不受影响继续运行。
### 邮件头取证
从邮件头中提取完整的 Received 链、源 IP 和身份验证结果（SPF、DKIM、DMARC）。通过 `dnspython` 执行实时 DNS 查找，以获取发件人域名的实际 SPF 和 DMARC TXT 记录。检测 Reply-To 不匹配、Return-Path 伪造、针对知名品牌的显示名称欺骗以及 NXDOMAIN 发件人域名。
### URL 分析
从纯文本和 HTML 正文内容中提取每个 URL，包括去诱饵格式（`hxxp://`、`[.]`）。发出实时 HTTP 请求以跟踪重定向链，捕获每一跳的状态码，并记录最终 URL、页面标题和服务器头信息。根据已知钓鱼域名列表检查 URL，检测基于 IP 的 URL、短链接、可疑 TLD 以及通过主要品牌的同形字比较检测域名抢注。
### IDN 同形字检测
检测国际化域名同形字攻击，即攻击者使用西里尔文、希腊文、亚美尼亚文或其他 Unicode 外观相似字符注册域名（例如 apple.com 中的西里尔字母 'a'）。识别混合脚本域名，解码 punycode，并将易混淆字符映射回拉丁字母以检测视觉冒充。
### 无头浏览器沙箱
通过 Playwright 在沙箱化的 Chromium 实例中渲染 URL。检测基于 JavaScript 的重定向（`window.location`、`document.location`）、meta refresh 标签、基于 iframe 的攻击和凭据收集表单（密码输入字段）。捕获最终渲染页面的屏幕截图供分析人员审查。比较浏览器渲染的最终 URL 与 HTTP 重定向最终 URL，以检测静态分析无法发现的仅 JS 重定向。
### HTML 相似度分析
将渲染后的钓鱼页面与 15 个已知品牌登录页面签名进行比较。基于页面标题、表单字段、CSS 标记、DOM 模式和品牌特定术语计算结构相似度得分。
### 递归 URL 分析
当 URL 经过多次跳转重定向时，链中的每个中间域名都会被独立分析。每个跳转域名都会根据钓鱼域名列表、可疑 TLD、基于 IP 的 URL 和同形字检测进行检查。这可以捕获多阶段钓鱼攻击，其中间重定向器本身已被入侵。
### 附件分析
计算每个附件的哈希值（MD5、SHA1、SHA256）。计算香农熵。通过魔术字节识别文件类型，并标记与声明的扩展名不匹配的情况。检测 VBA 宏标记和双扩展名攻击。根据本地监视列表和可选的 VirusTotal API 检查哈希值。
### YARA 规则扫描
根据 12 条捆绑的 YARA 规则扫描所有附件：凭据收集 HTML、混淆 JavaScript、数据渗出表单、VBA 自动执行宏、VBA 下载器、OLE 嵌入可执行文件、PDF JavaScript 漏洞利用、PDF 嵌入文件、可疑脚本、品牌冒充 HTML、zip 炸弹指示器和 RTF 漏洞利用。自定义规则可以添加到 `yara_rules/`。
### ML 分类
Random Forest + Logistic Regression 集成分类器（scikit-learn `VotingClassifier`），跨四个类别提取 38 个特征：
- **邮件头特征 (10):** SPF/DKIM/DMARC 结果、异常、伪造指示符
- **URL 特征 (12):** 钓鱼域名、基于 IP 的 URL、短链接、同形字、重定向深度
- **附件特征 (8):** 可执行文件、宏、熵、VirusTotal 命中、YARA 匹配
- **正文特征 (8):** 紧迫性关键词、JavaScript、外部表单、隐藏文本、内容长度
返回钓鱼置信度得分（0-100%）以及基于规则的评分。模型在首次使用时自动训练并持久化到 `ml_models/`。
### NLP 正文分析
根据五个类别的 51 种语言模式分析邮件文本：
| 类别 | 模式数 | 示例 |
|---|---|---|
| 紧迫性 | 19 | 时间压力、截止日期、账户暂停 |
| 威胁 | 8 | 法律行动、账户终止、数据丢失 |
| 冒充 | 8 | 权威声明、官方部门语言 |
| 语法异常 | 9 | ESL 模式、过度正式、异常措辞 |
| 社会工程学 | 7 | 中奖声明、保密要求、情感操纵 |
返回每个类别的得分（0-100）和加权综合得分。
### MITRE ATT&CK 映射
49 个发现到技术的映射，涵盖 8 个战术中的 28 个独特的 ATT&CK 子技术：Reconnaissance、Resource Development、Initial Access、Execution、Persistence、Defense Evasion、Credential Access 和 Command & Control。每个映射都包含针对 SOC 分析师的特定检测建议。
### 多源威胁情报
根据五个外部源丰富提取的 IOC：
| 源 | 数据 | 认证 |
|---|---|---|
| AbuseIPDB | IP 信誉评分 | API 密钥（免费层） |
| URLhaus | 已知恶意 URL/域名查询 | 无 |
| PhishTank | 已验证的钓鱼 URL 数据库 | API 密钥（可选） |
| AlienVault OTX | 带脉冲计数的 IOC 丰富 | API 密钥（免费层） |
| VirusTotal | 文件哈希 + URL 信誉 | API 密钥（免费层） |
所有源都是可选的。线程安全的速率限制可防止 API 配额耗尽。
### 威胁评分
加权评分引擎，在邮件头、URL、附件、正文内容、ML 分类、NLP 分析、HTML 相似度、IDN 同形字和威胁情报源方面具有 55 个指标权重。得分上限为 100。
| 等级 | 得分 | 解释 |
|---|---|---|
| 严重 | 70-100 | 几乎可以确定为钓鱼 |
| 高 | 50-69 | 强烈的钓鱼指标 |
| 中 | 30-49 | 可疑，需要审查 |
| 低 | 10-29 | 轻微异常 |
| 干净 | 0-9 | 未检测到威胁 |
### 导出格式
- **IOC JSON** — 聚合的 IP、域名、URL、电子邮件地址和文件哈希
- **STIX 2.1** — 符合标准的威胁情报包，用于 SIEM/SOAR 接收（Splunk、QRadar、Sentinel、MISP、OpenCTI）
- **PDF 报告** — 专业的事件文档，包含封面页、执行摘要、风险可视化、建议措施和完整技术发现
- **CSV** — 所有历史分析数据的批量导出
## 架构
```
.eml upload / forwarded email / browser extension
│
┌───────────────┼───────────────┐
│ │ │
Header Analysis URL Analysis Attachment Analysis
(SPF/DKIM/DMARC (HTTP detonation, (Hashing, entropy,
DNS lookups, homoglyphs, magic bytes, VBA,
forgery checks) IDN detection) YARA scanning)
│ │ │
│ ┌──────┴──────┐ │
│ │ │ │
│ Browser Recursive │
│ Detonation URL Check │
│ (Playwright) (per hop) │
│ │ │ │
│ └──────┬──────┘ │
│ │ │
└───────────────┼───────────────┘
│
┌─────────────────┼─────────────────┐
│ │ │
NLP Analysis ML Classification HTML Similarity
(51 patterns, (38 features, (15 brand
5 categories) ensemble model) signatures)
│ │ │
└─────────────────┼─────────────────┘
│
┌───────────┼───────────┐
│ │ │
IOC Extraction Threat MITRE ATT&CK
(IPs, domains, Intel Mapping
URLs, hashes) Feeds (49 mappings)
│ │ │
└───────────┼───────────┘
│
Threat Scoring
(55 weighted indicators)
│
┌─────────┬──────┼──────┬─────────┐
│ │ │ │ │
STIX 2.1 PDF WHOIS Notify Auto-Reply
Export Report Enrich (email/ (IMAP
slack) forward)
```
## 快速开始
### 前置条件
| 要求 | 版本 | 说明 |
|---|---|---|
| Python | 3.10+ | 推荐 3.12 |
| pip | 最新 | 随 Python 附带 |
| Git | 2.x+ | 用于克隆仓库 |
| Docker | 24+ | **可选** — 用于生产部署 |
### Windows
1. 从 [python.org](https://www.python.org/downloads/) **安装 Python**。在安装过程中，勾选 **"Add Python to PATH"**。
2. **克隆并设置项目：**
```
git clone
cd email-phish-analyzer
python -m venv venv
venv\Scripts\activate
pip install -r requirements.txt
playwright install chromium
```
3. **配置环境：**
```
copy .env.example .env
# 在编辑器中打开 .env 并设置 PHISH_SECRET, JWT_SECRET_KEY 等。
```
4. **运行应用程序：**
```
python app.py
```
打开 `http://127.0.0.1:5000`。默认管理员凭据：`admin@phishguard.local` / `changeme`。
### macOS
1. **安装 Python**（如果尚未可用）：
```
brew install python@3.12
```
2. **克隆并设置项目：**
```
git clone
cd email-phish-analyzer
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
playwright install chromium
```
3. **配置环境：**
```
cp .env.example .env
# 使用你的 secrets 编辑 .env：
# PHISH_SECRET=$(python3 -c "import secrets; print(secrets.token_hex(32))")
# JWT_SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_hex(32))")
```
4. **运行应用程序：**
```
python app.py
```
打开 `http://127.0.0.1:5000`。默认管理员凭据：`admin@phishguard.local` / `changeme`。
### Linux (Ubuntu/Debian)
1. **安装系统依赖：**
```
sudo apt update
sudo apt install python3.12 python3.12-venv python3-pip git
```
2. **克隆并设置项目：**
```
git clone
cd email-phish-analyzer
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
playwright install chromium
playwright install-deps
```
3. **配置环境：**
```
cp .env.example .env
# Generate secrets：
# python3 -c "import secrets; print(secrets.token_hex(32))"
# 将输出粘贴到 .env 中作为 PHISH_SECRET 和 JWT_SECRET_KEY
```
4. **运行应用程序：**
```
python app.py
```
打开 `http://127.0.0.1:5000`。默认管理员凭据：`admin@phishguard.local` / `changeme`。
### Docker Compose (生产环境)
1. **安装 Docker** — [Docker Desktop](https://www.docker.com/products/docker-desktop/) (Windows/macOS) 或 [Docker Engine](https://docs.docker.com/engine/install/) (Linux)。
2. **克隆并配置：**
```
git clone
cd email-phish-analyzer
cp .env.example .env
```
3. **生成密钥并编辑 `.env`：**
```
# Generate secure random keys：
python3 -c "import secrets; print('PHISH_SECRET=' + secrets.token_hex(32))"
python3 -c "import secrets; print('JWT_SECRET_KEY=' + secrets.token_hex(32))"
# 将输出粘贴到 .env。设置 FLASK_ENV=production 并配置
# DATABASE_URL, REDIS_URL 以及你需要的任何 API keys。
```
4. **启动所有服务：**
```
docker compose up -d
```
5. **验证服务正在运行：**
```
docker compose ps
```
这将启动五个服务：
| 服务 | 描述 | 端口 |
|---|---|---|
| web | Flask + Gunicorn | 5000 |
| worker | 带 Playwright 的 Celery 后台分析 | — |
| postgres | PostgreSQL 16 | 5432 |
| redis | Redis 7 (缓存、任务队列、速率限制) | 6379 |
| minio | S3 兼容的对象存储 | 9000 |
**有用的 Docker 命令：**
| 命令 | 描述 |
|---|---|
| `docker compose logs -f web` | 跟踪 Web 服务器日志 |
| `docker compose logs -f worker` | 跟踪 Celery worker 日志 |
| `docker compose restart web` | 重启 Web 服务器 |
| `docker compose down` | 停止所有服务 |
| `docker compose down -v` | 停止所有服务并移除卷 |
### 安装后检查清单
- [ ] 更改默认管理员密码（`admin@phishguard.local` / `changeme`）
- [ ] 配置首选项（email/Slack 阈值）
- [ ] 上传示例 `.eml` 文件以验证分析流水线正常工作
- [ ] 安装 [浏览器扩展](#browser-extension) 以进行 Gmail/Outlook 集成
- [ ] 如果使用共享分析收件箱，请配置 [IMAP 转发](#email-forwarding-imap)
### 运行测试
```
pip install pytest
python -m pytest tests/ -v
```
测试套件验证邮件解析、URL 分析、HTTP 沙箱、附件分析、VirusTotal 集成、邮件头取证、DNS 查找、IOC 提取、威胁评分、MITRE ATT&CK 映射、STIX 2.1 导出、WHOIS 查找、PDF 报告生成、数据库操作和完整的端到端流水线验证。
### 分支保护设置
要求 CI 检查通过后才能合并到 `main`：
1. 转到你的 GitHub 仓库 **Settings** > **Branches**
2. 点击 **Add branch protection rule**
3. 将 **Branch name pattern** 设置为 `main`
4. 启用 **Require status checks to pass before merging**
5. 搜索并选择以下必需的检查：
- `lint` — ruff 代码质量检查
- `security` — bandit 安全分析
- `test` — pytest 测试套件
6. 启用 **Require branches to be up to date before merging**
7. *（可选）* 启用 **Require a pull request before merging** 并设置所需的批准数量
8. 点击 **Save changes**
配置完成后，任何人都无法直接推送到 `main`——所有更改都必须通过 Pull Request 通过 lint、security 和 test 检查。
## 浏览器扩展
Chrome 扩展（Manifest V3）允许用户在不离开 Gmail 或 Outlook Web 的情况下分析邮件。
### 安装
1. 在 Chrome 中打开 `chrome://extensions/`
2. 启用 "Developer mode"
3. 点击 "Load unpacked" 并选择 `extension/` 目录
### 功能
- **右键菜单分析** — 选择文本或右键单击任何邮件页面以使用 PhishGuard 进行分析
- **工具栏按钮** — 注入的 "Analyze" 按钮会出现在 Gmail 和 Outlook 邮件工具栏中
- **弹出窗口** — 上传 `.eml` 文件、查看最近 3 个分析结果、配置服务器连接
- **徽章通知** — 扩展图标显示带有颜色编码徽章的威胁得分
- **浏览器通知** — 高/严重威胁的桌面警报
### 配置
点击 PhishGuard 扩展图标 > 设置链接，或右键点击图标 > "Options"。输入你的 PhishGuard 服务器 URL 和 API 密钥（JWT 令牌或旧版 API 密钥）。
## 邮件转发 (IMAP)
PhishGuard 可以通过 IMAP 监控共享邮箱。用户将可疑邮件转发到配置的地址（例如 `analyze@yourcompany.com`），PhishGuard 会自动：
1. 以可配置的间隔轮询收件箱（默认：60 秒）
2. 提取转发的邮件（支持 message/rfc822 附件、.eml 附件和内联转发）
3. 运行完整的分析流水线
4. 可选地发送包含结果和完整报告链接的电子邮件回复
### 设置
将 IMAP 凭据添加到你的 `.env` 文件：
```
IMAP_HOST=imap.gmail.com
IMAP_PORT=993
IMAP_USER=analyze@yourcompany.com
IMAP_PASS=your-app-password
IMAP_FOLDER=INBOX
IMAP_USE_SSL=true
IMAP_POLL_INTERVAL=60
IMAP_AUTO_REPLY=true
```
IMAP 轮询作为 Celery Beat 计划任务运行。确保 Celery worker 和 beat 调度器正在运行：
```
celery -A celery_worker.celery_app worker --beat --loglevel=info
```
## 配置
将 `.env.example` 复制到 `.env` 并进行配置。默认情况下，所有分析模块都已启用，并在缺少可选依赖项或 API 密钥时优雅降级。
### 关键变量
```
FLASK_ENV=development # development | staging | production
DATABASE_URL=postgresql://... # leave empty for SQLite in development
PHISH_SECRET= # Flask secret key
JWT_SECRET_KEY= # JWT signing key
```
### 可选集成
```
VT_API_KEY= # VirusTotal file hash + URL reputation
ABUSEIPDB_API_KEY= # AbuseIPDB IP reputation
OTX_API_KEY= # AlienVault OTX IOC enrichment
PHISHTANK_API_KEY= # PhishTank verified phishing URLs
GOOGLE_CLIENT_ID= # OAuth 2.0 Google login
MICROSOFT_CLIENT_ID= # OAuth 2.0 Microsoft login
```
### 通知配置
```
SMTP_HOST=smtp.gmail.com # SMTP server for email alerts
SMTP_PORT=587
SMTP_USER=alerts@yourcompany.com
SMTP_PASS=your-app-password
SMTP_FROM=phishguard@yourcompany.com
SLACK_WEBHOOK_URL= # Default Slack webhook for alerts
```
### 功能开关
```
BROWSER_DETONATION_ENABLED=true # Playwright headless browser
YARA_ENABLED=true # YARA rule scanning
ML_CLASSIFIER_ENABLED=true # ML phishing classification
NLP_ANALYSIS_ENABLED=true # NLP body analysis
HTML_SIMILARITY_ENABLED=true # Brand impersonation detection
THREAT_INTEL_ENABLED=false # External threat intel feeds
```
## 外部 API 设置
所有外部 API 都是可选的。当密钥不存在时，PhishGuard 会优雅降级。
### VirusTotal
1. 在 [virustotal.com](https://www.virustotal.com/gui/join-us) 创建一个免费帐户
2. 转到你的个人资料 → API Key
3. 复制 API 密钥并在 `.env` 中设置 `VT_API_KEY`
4. **速率限制：** 免费层允许 4 次请求/分钟，500 次/天
### AbuseIPDB
1. 在 [abuseipdb.com](https://www.abuseipdb.com/register) 创建一个免费帐户
2. 转到 Account → API → Create Key
3. 复制密钥并在 `.env` 中设置 `ABUSEIPDB_API_KEY`
4. 设置 `THREAT_INTEL_ENABLED=true`
5. **速率限制：** 免费层允许 1,000 次检查/天
### AlienVault OTX
1. 在 [otx.alienvault.com](https://otx.alienvault.com/accounts/signup) 创建一个免费帐户
2. 转到 Settings → API Integration → OTX Key
3. 复制密钥并在 `.env` 中设置 `OTX_API_KEY`
4. 设置 `THREAT_INTEL_ENABLED=true`
5. **速率限制：** 10,000 次请求/天
### PhishTank
1. 在 [phishtank.org](https://phishtank.org/register.php) 创建一个免费帐户
2. 转到 Developer Information → Manage Applications → Create Application
3. 复制应用密钥并在 `.env` 中设置 `PHISHTANK_API_KEY`
4. 设置 `THREAT_INTEL_ENABLED=true`
5. **速率限制：** 请保持礼貌（建议 1 次请求/秒）
## 环境变量参考
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
| `FLASK_ENV` | 否 | `production` | `development`、`staging` 或 `production` |
| `PHISH_SECRET` | **是** | 随机 | Flask 密钥（在生产环境中设置一个稳定的值） |
| `DATABASE_URL` | 否 | SQLite | 用于生产环境的 PostgreSQL 连接字符串 |
| `REDIS_URL` | 否 | `redis://localhost:6379/0` | 用于缓存和任务队列的 Redis 连接 |
| `CELERY_BROKER_URL` | 否 | `REDIS_URL` | Celery broker URL |
| `CELERY_RESULT_BACKEND` | 否 | `REDIS_URL` | Celery 结果后端 URL |
| `S3_ENDPOINT_URL` | 否 | — | 用于文件存储的 S3/MinIO 端点 |
| `S3_ACCESS_KEY` | 否 | — | S3 访问密钥 |
| `S3_SECRET_KEY` | 否 | — | S3 密钥 |
| `S3_BUCKET` | 否 | `phishguard-uploads` | S3 存储桶名称 |
| `JWT_SECRET_KEY` | **是** | `PHISH_SECRET` | JWT 签名密钥（在生产环境中单独设置） |
| `JWT_ACCESS_MINUTES` | 否 | `30` | JWT 访问令牌生命周期 |
| `JWT_REFRESH_DAYS` | 否 | `7` | JWT 刷新令牌生命周期 |
| `SESSION_TIMEOUT_MINUTES` | 否 | `60` | 浏览器会话超时 |
| `ADMIN_EMAIL` | 否 | `admin@phishguard.local` | 默认管理员邮箱（首次启动时创建） |
| `ADMIN_PASSWORD` | 否 | `changeme` | 默认管理员密码 |
| `VT_API_KEY` | 否 | — | VirusTotal API 密钥 |
| `ABUSEIPDB_API_KEY` | 否 | — | AbuseIPDB API 密钥 |
| `OTX_API_KEY` | 否 | — | AlienVault OTX API 密钥 |
| `PHISHTANK_API_KEY` | 否 | — | PhishTank API 密钥 |
| `THREAT_INTEL_ENABLED` | 否 | `false` | 启用外部威胁情报源 |
| `GOOGLE_CLIENT_ID` | 否 | — | Google OAuth 2.0 客户端 ID |
| `GOOGLE_CLIENT_SECRET` | 否 | — | Google OAuth 2.0 客户端密钥 |
| `MICROSOFT_CLIENT_ID` | 否 | — | Microsoft OAuth 2.0 客户端 ID |
| `MICROSOFT_CLIENT_SECRET` | 否 | — | Microsoft OAuth 2.0 客户端密钥 |
| `BROWSER_DETONATION_ENABLED` | 否 | `true` | 启用 Playwright 无头浏览器 |
| `YARA_ENABLED` | 否 | `true` | 启用 YARA 规则扫描 |
| `ML_CLASSIFIER_ENABLED` | 否 | `true` | 启用 ML 钓鱼分类器 |
| `NLP_ANALYSIS_ENABLED` | 否 | `true` | 启用 NLP 正文分析 |
| `HTML_SIMILARITY_ENABLED` | 否 | `true` | 启用品牌冒充检测 |
| `SMTP_HOST` | 否 | — | 用于邮件警报的 SMTP 服务器 |
| `SMTP_PORT` | 否 | `587` | SMTP 端口 |
| `SMTP_USER` | 否 | — | SMTP 用户名 |
| `SMTP_PASS` | 否 | — | SMTP 密码 |
| `SMTP_FROM` | 否 | `noreply@phishguard.local` | 邮件警报的发件人地址 |
| `SLACK_WEBHOOK_URL` | 否 | — | 用于警报的默认 Slack webhook |
| `IMAP_HOST` | 否 | — | 用于邮件转发的 IMAP 服务器 |
| `IMAP_USER` | 否 | — | IMAP 用户名 |
| `IMAP_PASS` | 否 | — | IMAP 密码 |
| `IMAP_POLL_INTERVAL` | 否 | `60` | IMAP 轮询之间的秒数 |
| `SENTRY_DSN` | 否 | — | 用于错误跟踪的 Sentry DSN |
| `SENTRY_TRACES_SAMPLE_RATE` | 否 | `0.1` | Sentry 性能跟踪采样率 (0.0–1.0) |
| `SENTRY_ENVIRONMENT` | 否 | `FLASK_ENV` | Sentry 环境标签 |
| `APP_BASE_URL` | 否 | `http://127.0.0.1:5000` | 通知链接的基础 URL |
| `BACKUP_RETENTION` | 否 | `7` | 要保留的数据库备份数量 |
## 监控与维护
### Sentry 错误跟踪
1. 在 [sentry.io](https://sentry.io) 创建一个项目（提供免费层）
2. 从 Project Settings → Client Keys 复制 DSN
3. 在 `.env` 中设置 `SENTRY_DSN`
4. 错误和性能跟踪会自动发送。设置 `SENTRY_TRACES_SAMPLE_RATE=0.1` (10%) 以控制量。
### 正常运行时间监控
1. 在 [uptimerobot.com](https://uptimerobot.com) 创建一个免费帐户
2. 添加一个新的 HTTP(s) 监视器，指向 `https://your-domain.com/health/ready`
3. 将检查间隔设置为 5 分钟
4. 当数据库和 Redis 都可访问时，`/health/ready` 端点返回 `200`，否则返回 `503`
**可用的健康端点：**
| 端点 | 目的 | 何时使用 |
|---|---|---|
| `GET /health` | 存活探针 — 应用正在运行 | Kubernetes 存活探针、Docker healthcheck |
| `GET /health/ready` | 就绪探针 — DB + Redis 可达 | UptimeRobot、负载均衡器健康检查 |
### 数据库备份
备份通过 `backup` 服务在 Docker Compose 中自动运行（每日，保留 7 个备份）。
**手动备份：**
```
python backup_db.py ./backups
```
**从备份恢复：**
```
pg_restore --host localhost --port 5432 --username phishguard --dbname phishguard --clean backups/phishguard_YYYYMMDD_HHMMSS.dump
```
**Docker 备份恢复：**
```
docker compose cp backup:/backups/phishguard_YYYYMMDD_HHMMSS.dump ./
docker compose exec postgres pg_restore -U phishguard -d phishguard --clean /tmp/backup.dump
```
## 运行全部服务
### 本地开发
```
# 1. Set up environment
cp .env.example .env
# 编辑 .env：设置 FLASK_ENV=development，生成 PHISH_SECRET 和 JWT_SECRET_KEY
# 2. Install dependencies
python -m venv venv
source venv/bin/activate # Windows: venv\Scripts\activate
pip install -r requirements.txt
playwright install chromium
# 3. Run the app (uses SQLite, no Redis/Celery needed)
python app.py
```
### Docker Compose (生产环境)
```
# 启动所有服务 (web, worker, postgres, redis, minio, backup)
docker compose up -d
# 检查服务健康状态
docker compose ps
# 查看日志
docker compose logs -f web
docker compose logs -f worker
# 停止所有内容
docker compose down
```
### 运行测试
```
pip install pytest
python -m pytest tests/ -v
```
测试使用内存中的 SQLite 数据库，禁用 Celery（同步分析），并且不需要 Redis、S3 或任何外部 API 密钥。
## 身份验证与安全
- **OAuth 2.0** — Google 和 Microsoft SSO
- **本地认证** — 使用 bcrypt 哈希的邮箱/密码注册
- **JWT API 认证** — 带撤销功能的访问/刷新令牌流
- **基于角色的访问控制** — Admin、analyst 和 viewer 角色，带有 RBAC 装饰器
- **CSRF 保护** — 每个表单都包含一个 CSRF 令牌
- **安全头** — Content Security Policy、X-Frame-Options、X-Content-Type-Options、X-XSS-Protection、HSTS（生产环境）
- **输入验证** — 多步 `.eml` 上传验证（扩展名、路径遍历、空文件、大小限制、二进制签名、魔术字节检测、RFC 5322 完整性）
- **速率限制** — API 端点上的每用户和每 IP 速率限制
- **日志** — 每个操作（分析、删除、导出）都记录用户、IP 和时间戳
## API 参考
所有端点都需要 JWT Bearer 令牌或 API 密钥认证。
### 身份验证
```
POST /api/auth/token Get JWT access + refresh tokens
POST /api/auth/refresh Refresh access token
POST /api/auth/revoke Revoke refresh token
```
### 分析
```
POST /api/analyze Upload .eml file for analysis
POST /api/extension/analyze Extension analysis endpoint (JSON body)
GET /api/job//status Poll background job status
GET /api/report/ Full analysis report (JSON)
GET /api/history All past analyses
DELETE /api/report/ Delete an analysis
```
### 导出
```
GET /api/iocs/ IOC export (JSON)
GET /api/stix/ STIX 2.1 bundle
GET /api/mitre/ MITRE ATT&CK mappings
GET /api/export/csv Bulk CSV export
```
### 分析统计
```
GET /api/stats Aggregate statistics
GET /api/trend?days=30 Daily trend data
```
### 管理
```
POST /api/admin/imap/test Test IMAP connectivity (admin only)
GET /api/admin/imap/status IMAP polling status
```
## 仪表板
SOC 仪表板提供电子邮件安全状况的概览：
- **时间段选择器** — 在 7 天、30 天和 90 天视图之间切换
- **SOC 叙述** — 当前威胁形势的通俗总结（“本周分析了 12 封邮件，检测到 3 个严重威胁，比上周增加 50%”）
- **威胁速度** — 显示威胁是在增加、减少还是稳定的趋势指示器
- **面积图** — 显示随时间变化的每日威胁水平的渐变填充趋势图
- **圆环图** — 威胁等级分布细分
- **快捷操作** — 新建分析、导出 CSV、查看历史的按钮
## 团队与组织
PhishGuard 支持多租户组织：
- **角色** — owner、admin、member，具有范围权限
- **组织范围分析** — 管理员查看所有组织分析，成员查看自己的
- **活动源** — 组织管理员查看最近的团队操作（分析、删除、导出、登录）
- **成员统计** — 每位成员的分析计数和严重威胁计数
- **团队导出** — 所有组织分析的 CSV 导出
## 通知
- **邮件警报** — 针对严重/高/中威胁的专业 HTML 电子邮件，包含建议措施
- **Slack webhooks** — Block Kit 格式的警报，包含威胁详细信息和报告链接
- **应用内通知** — 带有未读徽章的实时通知中心
- **可配置阈值** — 设置警报的最低分数，选择哪些级别触发 email/Slack
- **每周摘要** — 自动化的周一早晨摘要，包含威胁细分、趋势比较和内嵌图表
- **测试按钮** — 从首选项页面验证通知发送
## 自定义 YARA 规则
将 `.yar` 或 `.yara` 文件添加到 `yara_rules/` 目录。规则在启动时自动编译和加载。
```
rule Custom_Detection
{
meta:
description = "What this rule detects"
severity = "critical"
category = "phishing"
strings:
$pattern = "suspicious_string"
condition:
$pattern
}
```
支持的严重性值：`critical`、`high`、`medium`、`low`
支持的类别：`phishing`、`macro`、`exploit`、`script`、`embedded`、`evasion`
## 项目结构
```
email-phish-analyzer/
│
├── app.py Flask routes, middleware, pipeline orchestration
├── config.py Feature flags, scoring weights, watchlists, env config
├── models.py Dataclasses for all analysis entities
├── database.py SQLAlchemy ORM models (PostgreSQL / SQLite)
├── auth.py OAuth 2.0, JWT, RBAC, Flask-Login integration
├── storage.py S3 / MinIO file storage client
├── tasks.py Celery background tasks + Beat schedule
├── celery_worker.py Celery worker entry point
├── helpers.py Shared utility functions
│
├── email_parser.py .eml parsing, header/body extraction
├── header_analyzer.py SPF/DKIM/DMARC validation, live DNS lookups
├── url_analyzer.py HTTP detonation, heuristics, IDN homograph, recursive analysis
├── browser_detonator.py Playwright headless browser detonation
├── attachment_analyzer.py File hashing, entropy, magic bytes, VBA, VirusTotal, YARA
├── yara_scanner.py YARA rule compilation and scanning engine
│
├── ml_classifier.py Random Forest + Logistic Regression ensemble classifier
├── nlp_analyzer.py Urgency, threat, impersonation, grammar, social engineering
├── html_similarity.py Brand impersonation detection (15 brand signatures)
├── threat_intel.py AbuseIPDB, URLhaus, PhishTank, AlienVault OTX, VirusTotal
│
├── ioc_extractor.py IOC aggregation (IPs, domains, URLs, hashes, emails)
├── threat_scorer.py Weighted scoring engine (55 indicators)
├── mitre_mapper.py MITRE ATT&CK mapping (49 mappings, 28 techniques)
├── stix_exporter.py STIX 2.1 bundle generation
├── whois_lookup.py WHOIS domain intelligence
├── report_generator.py Professional PDF report generation
│
├── imap_poller.py IMAP inbox polling for forwarded email analysis
├── notifications.py Email, Slack, and in-app notification dispatch
│
├── extension/ Chrome browser extension (Manifest V3)
│ ├── manifest.json Extension manifest
│ ├── background.js Service worker, context menu, API calls
│ ├── content.js Gmail/Outlook email extraction + toolbar injection
│ ├── content.css Injected button + overlay styles
│ ├── popup.html/js Extension popup UI
│ ├── options.html/js Extension settings page
│ └── icons/ Extension icons (16/48/128)
│
├── static/
│ ├── css/style.css Main stylesheet (dark theme)
│ ├── js/dashboard.js Dashboard area + doughnut charts
│ ├── js/tooltips.js Security term tooltips + guided walkthrough
│ ├── js/utils.js Shared frontend utilities
│ └── fonts/ Inter + JetBrains Mono (PDF reports)
│
├── templates/ Jinja2 templates
│ ├── dashboard.html SOC dashboard with period selector + narrative
│ ├── report.html Analysis report with data-tip tooltips
│ ├── onboarding.html 6-step guided onboarding wizard
│ ├── team.html Team management + activity feed
│ ├── notifications.html Notification preferences + test button
│ ├── admin.html Admin panel with IMAP status
│ └── ... Login, register, history, etc.
│
├── ml_models/ Trained ML model storage
├── yara_rules/ YARA rule files (.yar)
├── screenshots/ Browser detonation screenshots
├── tests/ Test suite with sample .eml files
│
├── Dockerfile Production container (Python 3.12, Playwright, YARA)
├── docker-compose.yml Full stack: web, worker, postgres, redis, minio
├── requirements.txt Python dependencies
├── .env.example Environment variable reference
└── LICENSE MIT License
```
## 许可证
MIT License。有关详细信息，请参阅 [LICENSE](LICENSE)。
标签：Apex, Cloudflare, DNS 取证, IOC 提取, MITRE ATT&CK, NLP, PDF 报告, SOC 工具, STIX, STIX 2.1, YARA, 云资产可视化, 内核驱动漏洞利用, 头部分析, 威胁情报, 安全运营, 开发者工具, 扫描框架, 搜索引擎查询, 机器学习, 沙箱 detonation, 测试用例, 浏览器扩展, 特征检测, 网络安全, 置信度评分, 自动化分析, 请求拦截, 跨站脚本, 逆向工具, 邮件安全, 钓鱼邮件分析, 隐私保护