prasanna-vaddeman/email-threat-intelligence-platform
GitHub: prasanna-vaddeman/email-threat-intelligence-platform
一个端到端的机器学习平台，用于分析邮件内容并预测威胁等级，提供可解释的安全洞察。
Stars: 0 | Forks: 0
# 🛡️ 电子邮件威胁情报平台
这是一个端到端的机器学习平台，能够分析原始邮件内容并预测威胁等级，同时提供可解释的安全洞察。该平台使用现代化的FastAPI后端和交互式Streamlit前端构建，并已部署到生产环境进行监控。
## 🌐 在线演示
| 组件 | 链接 |
|------------|--------------------------------------------------------------|
| **前端** | [Streamlit 应用](https://email-threat-intelligence-platform-ai.streamlit.app/) |
| **后端 API** | [FastAPI 文档](https://email-threat-intelligence-platform-production.up.railway.app/docs) |
| **API 状态** | [状态检查](https://email-threat-intelligence-platform-production.up.railway.app/health) |
## 📋 目录
- [概述](#overview)
- [系统架构](#-system-architecture)
- [功能特性](#-features)
- [技术栈](#-tech-stack)
- [安装与设置](#-installation--setup)
- [项目结构](#-project-structure)
- [API 文档](#-api-documentation)
- [模型详情](#-model-details)
- [性能指标](#-performance-metrics)
- [部署](#-deployment)
- [监控与日志](#-monitoring--logging)
- [工程亮点](#-engineering-highlights)
- [贡献指南](#-contributing)
- [许可证](#-license)
- [作者](#-author)
## 概述
### 问题陈述
电子邮件威胁的演变速度远超传统垃圾邮件过滤器的适应能力。组织需要具备以下能力的智能系统：
- 同时检测垃圾邮件和复杂的网络钓鱼尝试
- 实时提取可操作的安全指标
- 提供可解释的威胁情报
- 在生产环境中可靠扩展
- 支持持续监控和可观察性
### 解决方案
本平台提供：
✅ **智能检测** - 结合NLP和工程特征的混合机器学习模型
✅ **实时分析** - 生产环境推理延迟低于100毫秒
✅ **生产就绪** - 已部署在Railway上，具备健康监控
✅ **可解释AI** - 详细的威胁评分和特征归因
✅ **可扩展架构** - 模块化服务，职责清晰分离
## 🏗 系统架构
```
┌─────────────────────────────────────────────────────────────┐
│ User Interface Layer │
│ (Streamlit Cloud - Frontend) │
└─────────────────────────────────────────────────────────────┘
↓
HTTP/REST API Call
↓
┌─────────────────────────────────────────────────────────────┐
│ FastAPI Backend (Railway) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ API Route Handler │ │
│ │ (request validation, response formatting) │ │
│ └──────────────────────────────────────────────────────┘ │
│ ↓ │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ Inference Pipeline Service │ │
│ │ ┌──────────────────────────────────────────────┐ │ │
│ │ │ 1. Text Preprocessing │ │ │
│ │ │ - Lowercasing, tokenization │ │ │
│ │ │ - Stopword removal, stemming │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ │ ↓ │ │
│ │ ┌──────────────────────────────────────────────┐ │ │
│ │ │ 2. Feature Engineering (Hybrid) │ │ │
│ │ │ - TF-IDF vectorization (sparse NLP) │ │ │
│ │ │ - Numerical threat signals (6 features) │ │ │
│ │ │ - StandardScaler normalization │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ │ ↓ │ │
│ │ ┌──────────────────────────────────────────────┐ │ │
│ │ │ 3. Model Inference │ │ │
│ │ │ - XGBoost prediction (hybrid features) │ │ │
│ │ │ - Probability calibration │ │ │
│ │ │ - Threat scoring & risk analysis │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ │ ↓ │ │
│ │ ┌──────────────────────────────────────────────┐ │ │
│ │ │ 4. Monitoring & Logging │ │ │
│ │ │ - WhyLogs profile generation │ │ │
│ │ │ - Structured logging │ │ │
│ │ │ - Inference metrics (latency, etc) │ │ │
│ │ └──────────────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
↓
JSON Response
{prediction, scores, features}
```
## ✨ 功能特性
### 邮件分类引擎
- **二元分类** - 区分垃圾邮件（恶意）与正常邮件（合法）
- **概率评分** - 返回经过校准的概率值，用于统计置信度
- **威胁等级** - 将风险分类为严重、高、中、低或安全
- **置信度指标** - 提供模型置信度百分比
### 高级特征提取
自动计算安全信号：
| 特征 | 用途 | 类型 | 示例 |
|----------------|--------------|------------|------------------|
| **URL 数量** | 检测钓鱼链接 | 数值型 | 检测到5个URL |
| **HTML 标签数** | 识别基于HTML的攻击 | 数值型 | 发现12个标签 |
| **大写比例** | 检测攻击性消息 | 数值型 | 23% 为大写字母 |
| **特殊字符数** | 标记混淆尝试 | 数值型 | 45个特殊字符 |
| **垃圾邮件关键词** | 模式匹配 | 数值型 | 检测到3个关键词 |
| **感叹号数量** | 紧急/情绪检测 | 数值型 | 3个感叹号 |
| **TF-IDF 向量化** | 语义文本模式 | 稀疏NLP向量 | 300+ 维度 |
### 生产特性
- **快速推理** - 针对实时生产使用进行优化
- **API文档** - 自动生成的Swagger UI
- **健康检查** - 端点监控和可用性
- **结构化日志** - 便于调试的日志输出
- **错误处理** - 优雅的失败模式
## 🛠 技术栈
### 机器学习与NLP
- **scikit-learn** - 特征提取与预处理
- **XGBoost** - 梯度提升分类器（生产模型）
- **TF-IDF** - 文本向量化与特征工程
- **NLTK** - 自然语言处理工具
- **pandas** - 数据操作与分析
- **joblib** - 模型序列化与加载
### 后端与API
- **FastAPI** - 现代化异步Python Web框架
- **Uvicorn** - ASGI应用服务器
- **Pydantic** - 数据验证与解析
- **Python 3.11** - 开发环境
### 前端
- **Streamlit** - 交互式Python Web应用框架
- **streamlit-cloud** - 无服务器部署
### 部署与基础设施
- **Railway** - 云平台（后端）
- **Streamlit Cloud** - 云平台（前端）
- **Git/GitHub** - 版本控制
### 监控与可观察性
- **WhyLogs** - 本地数据画像与监控
- **Python logging** - 结构化日志
- **UptimeRobot** - 健康监控（正常运行时间跟踪）
### 开发工具
- **pytest** - 单元测试框架
- **black** - 代码格式化
- **pylint** - 代码质量分析
## 🚀 安装与设置
### 前置条件
- Python 3.11+
- Git
- pip (或 conda)
- 虚拟环境（推荐）
### 本地开发
**1. 克隆仓库**
```
git clone https://github.com/prasanna-vaddeman/email-threat-intelligence-platform.git
cd email-threat-intelligence-platform
```
**2. 创建虚拟环境**
```
python -m venv venv
# 激活虚拟环境
# 在 Windows 上：
venv\Scripts\activate
# 在 macOS/Linux 上：
source venv/bin/activate
```
**3. 安装依赖**
```
pip install -r requirements.txt
```
**4. 配置环境变量**
```
# 复制示例配置
cp .env.example .env
# 编辑 .env 文件并添加您的配置
nano .env # or use your editor
```
需要的环境变量：
```
# 可选：WhyLabs 监控凭据（留空以使用仅限本地监控）
WHYLABS_API_KEY=
WHYLABS_ORG_ID=
WHYLABS_DATASET_ID=
# 配置
SPAM_THRESHOLD=0.5
LOG_LEVEL=INFO
```
**5. 运行后端服务器**
```
cd backend
python -m uvicorn main:app --reload --host 0.0.0.0 --port 8000
```
后端将在以下地址可用：`http://localhost:8000`
API文档地址：`http://localhost:8000/docs`
**6. 运行前端（在单独终端中）**
```
streamlit run frontend/app.py
```
前端将在以下地址可用：`http://localhost:8501`
## 📁 项目结构
```
email-threat-intelligence-platform/
│
├── backend/ # FastAPI backend
│ ├── api/
│ │ ├── __init__.py
│ │ └── routes.py # API endpoints (POST /predict)
│ ├── schemas/
│ │ ├── __init__.py
│ │ └── email_schema.py # Request/response validation
│ ├── services/
│ │ ├── __init__.py
│ │ ├── inference.py # Prediction pipeline
│ │ ├── preprocessing.py # Text cleaning
│ │ ├── vectorization.py # TF-IDF vectorization
│ │ ├── feature_engineering.py # Threat signal extraction
│ │ └── [other services]
│ ├── utils/
│ │ ├── __init__.py
│ │ ├── config.py # Configuration management
│ │ └── threat_utils.py # Threat scoring logic
│ └── main.py # FastAPI app entry point
│
├── frontend/ # Streamlit frontend
│ ├── components/
│ │ ├── __init__.py
│ │ ├── input_panel.py # Email input handling
│ │ ├── prediction_payload.py # Result display
│ │ ├── feature_panel.py # Feature visualization
│ │ ├── kpi_cards.py # Metrics cards
│ │ ├── header.py # UI header
│ │ ├── sidebar.py # Sidebar navigation
│ │ └── system_health.py # Health status
│ ├── services/
│ │ ├── __init__.py
│ │ └── api_client.py # Backend API calls
│ ├── utils/
│ │ ├── __init__.py
│ │ ├── colors.py # Color scheme
│ │ └── config.py # Frontend config
│ └── app.py # Streamlit entry point
│
├── monitoring/ # Monitoring & logging
│ ├── logs/
│ │ └── profiles/ # WhyLogs profiles
│ ├── __init__.py
│ ├── monitoring_service.py # Logging orchestration
│ ├── whylogs_logger.py # WhyLogs integration
│ └── whylabs_config.py # Configuration
│
├── models/ # Pre-trained ML artifacts
│ ├── advanced_xgboost_model.pkl # Production model (hybrid features)
│ ├── logistic_regression_model.pkl
│ ├── random_forest_model.pkl
│ └── [other trained models]
│
├── artifacts/ # ML artifacts
│ ├── tfidf_vectorizer.pkl # TF-IDF feature extraction
│ ├── standard_scaler.pkl # Numerical feature scaling
│ └── [other artifacts]
│
├── data/ # Dataset
│ ├── raw/ # Raw email data
│ │ ├── easy_ham_1/
│ │ ├── easy_ham_2/
│ │ ├── spam_1/
│ │ └── spam_2/
│ ├── interim/ # Processed data
│ ├── processed/ # Final dataset
│ └── feature_engineered/ # Hybrid feature datasets
│
├── notebooks/ # Jupyter notebooks
│ ├── 01_project_understanding.ipynb
│ ├── 02_email_parsing_experiments.ipynb
│ ├── 03_text_preprocessing.ipynb
│ ├── 04_exploratory_data_analysis.ipynb
│ ├── 05_feature_engineering.ipynb
│ ├── 06_model_training.ipynb
│ └── 07_inference_pipeline.ipynb
│
├── tests/ # Unit & integration tests
│ ├── __init__.py
│ ├── test_preprocessing.py
│ ├── test_inference.py
│ └── test_api.py
│
├── Procfile # Railway deployment config
├── requirements.txt # Python dependencies
├── .env.example # Example environment variables
├── .gitignore # Git ignore rules
├── README.md # This file
└── pyproject.toml # Project metadata
```
## 📡 API 文档
### 基础URL
**生产环境:** `https://email-threat-intelligence-platform-production.up.railway.app`
**本地:** `http://localhost:8000`
### 交互式API文档
访问 `/docs` 获取 Swagger UI 或 `/redoc` 获取 ReDoc 文档
```
https://email-threat-intelligence-platform-production.up.railway.app/docs
```
### 预测端点
**端点:** `POST /api/predict`
**请求体:**
```
{
"email_text": "string"
}
```
**示例请求:**
```
curl -X POST "https://email-threat-intelligence-platform-production.up.railway.app/api/predict" \
-H "Content-Type: application/json" \
-d '{
"email_text": "CLICK HERE NOW!!! You have won $1000000. Click the link: http://example.com/scam"
}'
```
**响应 (200 OK):**
```
{
"prediction": "spam",
"spam_probability": 94.23,
"threat_score": 94,
"confidence": 94.23,
"threat_level": "Critical",
"inference_ms": 45.32,
"features": {
"url_count": 1,
"html_tag_count": 0,
"uppercase_ratio": 0.2154,
"special_char_count": 12,
"spam_keyword_count": 3,
"exclamation_count": 3
}
}
```
**响应字段:**
| 字段 | 类型 | 描述 |
|------------------|--------|-------------------------------------|
| `prediction` | 字符串 | "spam" 或 "ham" |
| `spam_probability` | 浮点数 | 置信度百分比 (0-100) |
| `threat_score` | 整数 | 威胁严重程度 (0-100) |
| `confidence` | 浮点数 | 模型置信度 (0-100) |
| `threat_level` | 字符串 | 风险类别 (严重/高/中/低/安全) |
| `inference_ms` | 浮点数 | 推理延迟（毫秒） |
| `features` | 对象 | 提取的邮件特征 |
### 错误响应
**400 错误请求:**
```
{
"detail": "Email text is required"
}
```
**500 内部服务器错误:**
```
{
"detail": "Internal server error"
}
```
## 🤖 模型详情
### 混合特征工程方法
本平台采用**混合特征工程**策略，结合：
**1. NLP特征（稀疏）**
- TF-IDF向量化捕获语义模式
- 来自邮件内容的300+文本特征
- 识别常见的垃圾邮件词汇和模式
**2. 威胁情报特征（密集数值型）**
- URL数量 - 超链接数量（钓鱼指标）
- HTML标签数 - HTML元素（格式化攻击）
- 大写比例 - 攻击性消息模式
- 特殊字符数 - 混淆尝试
- 垃圾邮件关键词数 - 已知恶意术语
- 感叹号数量 - 紧急信号
**3. 特征归一化**
- 对数值特征应用StandardScaler
- 防止大值特征占主导地位
- 提高训练期间的优化稳定性
这种混合方法结合了语义理解（来自NLP）和安全指标（来自工程特征），创建了一个强大的检测系统，用于生产中的垃圾邮件检测和电子邮件安全系统。
### 模型选择过程
使用混合特征工程方法评估了多种分类算法：
| 模型 | 准确率 | 精确率 | 召回率 | F1分数 |
|--------------------------|----------|----------|----------|---------|
| 逻辑回归 | 98.18% | 100.00% | 94.35% | 97.10% |
| 朴素贝叶斯 | 98.61% | 99.72% | 95.97% | 97.81% |
| 决策树 | 92.96% | 90.76% | 87.10% | 88.89% |
| 随机森林 | 97.13% | 100.00% | 91.13% | 95.36% |
| XGBoost | 97.13% | 98.57% | 92.47% | 95.42% |
| 逻辑回归（调优后） | 97.57% | 99.14% | 93.28% | 96.12% |
| 随机森林（调优后） | 97.91% | 99.43% | 94.09% | 96.69% |
| **XGBoost（调优后）** | **98.61%** | **98.37%** | **97.31%** | **97.84%** |
**选择理由：**
选择超参数调优后的XGBoost作为生产模型，原因如下：
- **最高准确率** - 测试集上98.61%的分类正确率
- **优秀精确率** - 98.37%的垃圾邮件预测是正确的（误报少，被阻止的合法邮件更少）
- **出色召回率** - 97.31%的实际垃圾邮件被检测到（漏报少，逃过的危险邮件更少）
- **平衡的F1分数** - 97.84%（平衡精确率和召回率的最佳综合指标）
- **对混合特征鲁棒** - 梯度提升能有效处理稀疏NLP和密集数值特征
- **生产稳定性** - 经过实战检验，广泛应用于工业界
- **快速推理** - 亚100毫秒的预测延迟，适合实时使用
### 生产模型：XGBoost与混合特征
**文件:** `models/advanced_xgboost_model.pkl`
**架构:**
- **算法:** 梯度提升（XGBoost）
- **输入特征:** 300+ TF-IDF特征（稀疏NLP）+ 6个工程数值特征（密集），经StandardScaler归一化
- **训练数据集:** 综合的垃圾邮件和正常邮件语料库，配有全面的预处理管道
- **序列化:** joblib（快速，Python原生）
- **工件依赖:**
- `tfidf_vectorizer.pkl` - 将新邮件转换为TF-IDF向量
- `standard_scaler.pkl` - 归一化数值威胁信号
## 📊 性能指标
### 模型性能（测试集）
```
XGBoost with Hybrid Features Results:
──────────────────────────────────────
Accuracy: 98.61%
Precision: 98.37%
Recall: 97.31%
F1 Score: 97.84%
```
**这些指标的含义:**
- **准确率:** 98.61%的预测是正确的
- **精确率:** 98.37%被预测为垃圾邮件的邮件确实是垃圾邮件（低误报率 - 被阻止的合法邮件更少）
- **召回率:** 97.31%的实际垃圾邮件被检测到（低漏报率 - 逃过的危险邮件更少）
- **F1分数:** 97.84%的精确率和召回率平衡性能
**实际影响:**
- 在1000封垃圾邮件中，约973封被检测到
- 在100封被预测为垃圾邮件的邮件中，约98封确实是垃圾邮件
- 误报率：约1.63%（合法邮件被错误标记为垃圾邮件）
- 漏报率：约2.69%（垃圾邮件被错误标记为合法邮件）
### 推理性能
针对低延迟生产推理进行了优化。
## 🚀 部署
### 前端部署（Streamlit Cloud）
**平台:** Streamlit Cloud
**URL:** https://email-threat-intelligence-platform-ai.streamlit.app/
**部署:** GitHub推送时自动部署
**步骤:**
1. 将代码推送到GitHub
2. 将仓库连接到Streamlit Cloud
3. Streamlit在推送时自动部署
### 后端部署（Railway）
**平台:** Railway
**URL:** https://email-threat-intelligence-platform-production.up.railway.app/
**运行时:** Python 3.11 开发环境
Railway部署运行时已配置为云兼容。
**配置文件:**
**Procfile**（启动命令）:
```
web: python -m uvicorn backend.main:app --host 0.0.0.0 --port $PORT
```
**requirements.txt**（依赖项）:
```
fastapi==0.104.1
uvicorn==0.24.0
pydantic==2.4.2
scikit-learn==1.3.2
xgboost==2.0.0
pandas==2.1.1
joblib==1.3.2
whylogs==1.1.14
python-dotenv==1.0.0
```
**部署步骤:**
1. 创建Railway账户
2. 连接GitHub仓库
3. Railway在推送时自动部署
4. 在Railway仪表板中查看日志
### 环境变量（生产环境）
在Railway仪表板中设置：
```
SPAM_THRESHOLD=0.5
LOG_LEVEL=INFO
```
## 📈 监控与日志
### 监控栈
- **WhyLogs 本地画像监控** - 预测数据画像和日志记录
- **UptimeRobot** - API可用性监控
- **Python 结构化日志** - 应用级日志
### WhyLogs 集成
**目的:** 跟踪预测数据并生成本地画像
**实现:**
- 记录预测特征和结果
- 生成统计画像
- 将画像存储在本地 `monitoring/logs/profiles/` 目录
- 无云依赖 - 完全本地运行
**文件:**
- `monitoring/whylogs_logger.py` - 画像生成
- `monitoring/monitoring_service.py` - 集成点
### 结构化日志
所有服务使用Python内置日志：
```
import logging
LOGGER = logging.getLogger(__name__)
LOGGER.info("Email predicted as spam")
LOGGER.warning("Low confidence prediction")
LOGGER.error("Model loading failed")
```
### UptimeRobot 监控
监控API健康端点：
```
GET /health
```
跟踪：
- API可用性
- 响应时间
- 停机警报
## 🎯 工程亮点
生产工程决策：
- **混合特征工程** - 结合稀疏NLP（TF-IDF）和密集数值威胁信号以实现鲁棒检测
- **模块化后端架构** - 为预处理、向量化、特征工程、推理和监控分离服务
- **模型工件版本控制** - 存储多个训练模型以进行比较和回滚
- **Railway部署自动化** - Git推送触发自动构建和部署管道
- **Streamlit前端部署** - 在Streamlit Cloud上单独部署前端，可独立扩展
- **API健康监控** - 带有UptimeRobot集成的健康检查端点，用于24/7正常运行时间跟踪
- **本地预测可观察性** - WhyLogs用于监控预测，无需外部云依赖
- **特征归一化** - 对数值特征应用StandardScaler以防止特征主导
- **结构化日志系统** - 跨服务一致的日志记录，便于调试和可观察性
- **生产推理管道** - 独立的优化推理路径，用于延迟关键操作
## 🧪 测试
### 运行测试
```
# 安装测试依赖项
pip install pytest pytest-cov
# 运行所有测试
pytest
# 运行覆盖率报告
pytest --cov=backend --cov=frontend
# 运行特定测试文件
pytest tests/test_inference.py -v
```
### 测试结构
```
tests/
├── test_preprocessing.py # Text cleaning tests
├── test_inference.py # Prediction pipeline tests
├── test_api.py # API endpoint tests
└── conftest.py # Test fixtures
```
## 📄 许可证
本项目采用MIT许可证 - 详情请见LICENSE文件。
## 👨💻 作者
**Prasanna Kumar**
机器学习工程师 | 数据科学家
**链接:**
- 🔗 GitHub: https://github.com/prasanna-vaddeman
- 📧 邮箱: [your-email@example.com]
- 💼 LinkedIn: [your-linkedin-url]
## 🙏 致谢
- XGBoost团队提供的强大梯度提升库
- FastAPI提供的现代化Web框架
- Streamlit用于快速ML应用开发
- Railway用于无缝云部署
- WhyLogs提供的监控和画像功能
标签：AMSI绕过, AV绕过, Caido项目解析, FastAPI, Kubernetes, ML部署, Streamlit, 可解释AI, 垃圾邮件过滤, 威胁检测, 威胁评分, 安全见解, 实时分析, 机器学习平台, 混合模型, 特征工程, 生产就绪, 电子邮件威胁情报, 网络钓鱼检测, 访问控制, 逆向工具, 部署监控