VenkatNandaKishore/PhishGuard-LLM
GitHub: VenkatNandaKishore/PhishGuard-LLM
一个完全本地运行的实时邮件钓鱼检测系统，通过多阶段 ML 流水线在用户打开邮件前完成分类，并用本地 LLM 生成可读解释。
Stars: 0 | Forks: 0
# PhishGuard AI 🛡️
**一个完全在本地机器上运行的实时、可解释的网络钓鱼检测系统——无需云服务，无需 GPU。**
PhishGuard AI 会持续监控您的收件箱，在您打开每封邮件前对其进行分类，并用平实的语言准确解释邮件被标记的原因。
## 📋 目录
- [概述](#overview)
- [核心结果](#key-results)
- [系统架构](#system-architecture)
- [功能特性](#features)
- [技术栈](#tech-stack)
- [安装说明](#installation)
- [配置](#configuration)
- [使用方法](#usage)
- [数据集](#dataset)
- [模型训练](#model-training)
- [项目结构](#project-structure)
- [已知局限性](#known-limitations)
- [路线图](#roadmap)
- [作者](#authors)
- [许可证](#license)
## 概述
电子邮件钓鱼每年造成数十亿美元的损失，并导致全球超过 80% 的数据泄露事件。现有的防御措施都有一个相同的盲区：**邮件投递与您打开它之间的时间窗口。**
PhishGuard AI 关闭了这个窗口。它作为后台进程在您自己的机器上运行，在收件箱渲染之前，通过多阶段 ML 流水线扫描每一封到达的邮件。当检测到威胁时，设备上的语言模型会撰写简短的解释，指出具体的警告信号——没有二进制警报，没有神秘分数。
**以前没有系统同时做到这三点：**
- 完全本地执行——任何数据都不会离开您的设备
- 包含无链接钓鱼攻击的检测覆盖范围
- 非专业用户也能理解的自然语言解释
## 核心结果
在包含 **10,000 封电子邮件**的保留测试集上进行了评估：
| 指标 | 值 | 95% CI |
|---|---|---|
| 总体准确率 | **96.8%** | [96.2%, 97.4%] |
| F1分数 (钓鱼) | **94.9%** | [94.2%, 95.7%] |
| 假阳性率 | **4.8%** | [4.2%, 5.4%] |
| 假阴性率 | **5.3%** | [4.7%, 5.9%] |
| AUC-ROC | **0.980** | [0.977, 0.983] |
| 马修斯相关系数 | **0.930** | [0.925, 0.935] |
| 可疑邮件检测率 | **89.3%** | [87.9%, 90.7%] |
| 同步分类延迟 | **~230 ms** | — |
| 内存占用 | **~310 MB** | — |
**基线比较：**
| 系统 | 准确率 | 假阴性率 | 本地化? | 可解释? |
|---|---|---|---|---|
| **PhishGuard AI ( ours )** | **96.8%** | **5.3%** | ✅ | ✅ |
| Chiew et al. [24] hybrid | 94.8% | 7.4% | ❌ | ❌ |
| DistilBERT standalone | 94.3% | 6.9% | ✅ | ❌ |
| LightGBM (structural) | 93.1% | 8.7% | ✅ | 部分 |
| Random Forest | 92.4% | 10.2% | ✅ | 部分 |
| SVM (RBF) | 89.7% | 14.1% | ✅ | ❌ |
| Naive Bayes | 87.2% | 18.3% | ✅ | ❌ |
通过 McNemar 配对检验证明，所有改进均具有统计学意义（p < 0.001 对比所有基线）。
## 系统架构
```
┌─────────────────────────────────────────────────────────────┐
│ PhishGuard AI Pipeline │
│ (fully client-side, zero egress) │
└─────────────────────────────────────────────────────────────┘
IMAP / Gmail API
│
▼
┌──────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Email │───▶│ Feature │───▶│ DistilBERT │
│ Fetcher │ │ Extractor │ │ NLP Scorer │
└──────────────┘ │ (37 structural │ │ (feature #38) │
│ features) │ └────────┬────────┘
└──────────────────┘ │
▼
┌─────────────────┐
│ LightGBM │
│ Classifier │
│ Safe/Susp/Phish │
└────────┬────────┘
│
┌──────────────────────┼────────────────────┐
│ │ │
▼ ▼ ▼
┌──────────────────┐ ┌──────────────┐ ┌──────────────────┐
│ Quarantine + │ │ Phi-2 LLM │ │ SQLite Audit │
│ Notification │ │ Explainer │ │ Log + Feedback │
│ (sync, ~230ms) │ │ (async,~1s) │ │ │
└──────────────────┘ └──────────────┘ └──────────────────┘
```
**六个模块，全部在本地运行：**
1. **邮件获取器** — IMAP / Gmail API（只读，OAuth 2.0）
2. **特征提取器** — 38 维向量（邮件头，URL，内容，NLP）
3. **DistilBERT NLP 评分器** — 微调的钓鱼可能性得分
4. **LightGBM 分类器** — 三分类输出：安全 / 可疑 / 钓鱼
5. **Phi-2 解释器** — 设备上的自然语言解释（通过 Ollama）
6. **响应与记录器** — 隔离，通知，SQLite 审计日志
## 功能特性
- 🔒 **完全本地** — 邮件内容永远不会离开您的设备
- ⚡ **快速** — ~230 ms 内完成同步分类
- 🧠 **混合 ML** — 结构特征 + NLP + LLM 解释
- 📊 **三分类输出** — 安全 / 可疑 / 钓鱼（非简单的二进制）
- 💬 **平实语言警报** — Phi-2 解释*为什么*邮件被标记
- 🔄 **自适应** — 用户纠正反馈到定期重训练中
- 🖥️ **桌面通知** — Plyer / ToastNotifier 集成
- 📁 **自动隔离** — 被标记的邮件移至专用文件夹
- 🔍 **无链接检测** — 仅使用 NLP 捕获没有 URL 的钓鱼攻击
- 📝 **审计日志** — 每次分类的完整 SQLite 历史记录
## 技术栈
| 组件 | 技术 |
|---|---|
| 核心语言 | Python 3.10+ |
| ML 分类器 | LightGBM + Scikit-learn |
| NLP 模型 | DistilBERT（微调，Hugging Face） |
| LLM 解释器 | Phi-2 via Ollama（27亿参数） |
| 邮件访问 | IMAPClient，Gmail API |
| HTML 解析 | BeautifulSoup4 |
| URL 分析 | tldextract，python-whois |
| 调度 | APScheduler |
| 数据库 | SQLite |
| 通知 | Plyer，ToastNotifier |
| 打包 | PyInstaller |
## 安装说明
### 前置条件
- Python 3.10 或更高版本
- 已安装并在本地运行 [Ollama](https://ollama.ai)
- Gmail API 凭据（可选——也支持 IMAP）
### 1. 克隆代码库
```
git clone https://github.com/VenkatNandaKishore/PhishGuard-LLM.git
cd Phishguard-LLM
```
### 2. 创建虚拟环境
```
python -m venv venv
source venv/bin/activate # Linux / macOS
venv\Scripts\activate # Windows
```
### 3. 安装依赖项
```
pip install -r requirements.txt
```
### 4. 通过 Ollama 拉取 Phi-2 模型
```
ollama pull phi
```
### 5. 设置环境变量
```
cp .env.example .env
```
使用您的凭据编辑 `.env`（参见[配置](#configuration)）。
### 6. 运行监控程序
```
python monitor.py
```
## 配置
将 `.env.example` 复制到 `.env` 并填写：
```
# 要监控的电子邮件账户
EMAIL_ADDRESS=your@email.com
EMAIL_PASSWORD=your_app_password
# IMAP 设置（留空以改用 Gmail API）
IMAP_SERVER=imap.gmail.com
IMAP_PORT=993
# Alert 通知 — 从此地址发送 Alert
ALERT_SENDER_EMAIL=phishguardai@gmail.com
ALERT_SENDER_PASSWORD=your_alert_app_password
# Alert 通知 — 将 Alert 发送到此地址
ALERT_RECIPIENT_EMAIL=your@email.com
# Anthropic API key（可选 — 用于基于 Claude 的解释）
ANTHROPIC_API_KEY=your_key_here
# 轮询间隔，以秒为单位（默认：60）
POLL_INTERVAL=60
```
**Gmail 用户：** 您需要一个[应用专用密码](https://support.google.com/accounts/answer/185833)，而不是您的常规密码。
## 使用方法
### 启动监控
```
python monitor.py
```
监控程序将会：
1. 连接到您的收件箱
2. 对每一封新收到的邮件进行分类
3. 自动隔离检测到的钓鱼邮件
4. 发送带有 AI 生成解释的桌面通知
5. 将所有结果记录到 `data/phishguard.db`
### 查看检测历史
```
python dashboard.py
```
### 根据您的纠正重训练模型
```
python training/train_lgbm.py
```
### 运行测试套件
```
pytest tests/
```
## 数据集
我们在来自七个公开数据源的约 **130,000 封带标签电子邮件** 上进行了训练：
| 来源 | 类别 | 数量 | 时间段 |
|---|---|---|---|
| Nazario Phishing Corpus | 钓鱼 | ~3,661 | 2020–2025 |
| APWG Public Repository | 钓鱼 | ~15,000 | 2018–2023 |
| Academic Datasets (Berkeley / MIT) | 钓鱼 | ~20,000 | 混合 |
| TREC 2007 Spam Track | 钓鱼 | ~40,842 | 2007 |
| SpamAssassin Public Corpus | 钓鱼 | ~497 | 2002–2006 |
| Enron Email Dataset (anonymized) | 合法 | ~60,000 | 1998–2002 |
| Synthetic Business Email | 合法 | ~10,000 | 2023 |
- 两名独立审查员对所有样本进行标注（κ = 0.91）
- 合法与钓鱼邮件的比例为 60 / 40
- 在数据划分中保持时间顺序，以防止数据泄漏
## 模型训练
### 特征提取（38 个特征）
| 分组 | 数量 | 示例 |
|---|---|---|
| 邮件头认证 | 8 | SPF/DKIM/DMARC 结果，Reply-To 不匹配，路由异常 |
| 正文内容 | 7 | TF-IDF 紧急度得分，HTML 复杂度，图像数量 |
| URL 分析 | 10 | 域名年龄，短链接检测，TLD 风险，威胁情报源 |
| NLP (DistilBERT) | 1 | 微调的钓鱼可能性得分 |
### LightGBM 超参数
| 参数 | 值 |
|---|---|
| n_estimators | 200 |
| learning_rate | 0.05 |
| max_depth | 7 |
| num_leaves | 31 |
| feature_fraction | 0.8 |
| bagging_fraction | 0.8 |
| class_weight | balanced |
| objective | multiclass |
| early_stopping | 50 rounds |
### 从头开始重训练
```
# 构建 dataset
python training/build_dataset.py
# 训练 LightGBM
python training/train_lgbm.py
# Fine-tune DistilBERT（可选 — 已包含预训练权重）
python training/train_distilbert.py
```
## 项目结构
```
phishguard-ai/
├── monitor.py # Main monitoring loop
├── config/
│ └── settings.py # Configuration loader
├── modules/
│ ├── email_fetcher.py # IMAP / Gmail API connector
│ ├── email_parser.py # Header + body + URL extraction
│ ├── feature_extractor.py # 38-feature pipeline
│ ├── nlp_model.py # DistilBERT inference
│ ├── lgbm_classifier.py # LightGBM classifier
│ ├── explainer.py # Phi-2 / Claude explanation generator
│ ├── notifier.py # Desktop + email alerts
│ ├── database.py # SQLite audit log
│ └── domain_intelligence.py # Threat feed + WHOIS lookups
├── training/
│ ├── train_lgbm.py # LightGBM training script
│ ├── train_distilbert.py # DistilBERT fine-tuning script
│ └── build_dataset.py # Dataset assembly pipeline
├── data/
│ ├── models/ # Saved model weights
│ └── phishguard.db # SQLite detection log
├── tests/
│ ├── test_full_pipeline.py
│ ├── test_adversarial.py
│ └── test_phase2.py
├── .env.example
├── requirements.txt
└── README.md
```
## 已知局限性
| 局限性 | 影响 | 计划修复方案 |
|---|---|---|
| 无附件分析 | 无法检测 PDF/Office 宏有效载荷 | 沙盒集成 (v2) |
| 纯图像钓鱼 | 极少文本会降低 NLP 效果 | OCR 集成 (v2) |
| 仅支持英文 | 对非英文钓鱼活动的检测不可靠 | 多语言 DistilBERT (v2) |
| 手动重训练 | 概念漂移需要用户纠正 | 主动学习 (v2) |
| WHOIS 延迟 | 每次查询最多 3 秒，偶尔失败 | 缓存威胁情报 (进行中) |
## 路线图
- [ ] PDF 和 Office 宏沙盒分析
- [ ] 用于纯图像钓鱼的 OCR
- [ ] 多语言 DistilBERT 变体
- [ ] 基于熵的主动学习，用于自动纠正漂移
- [ ] 企业模式——SIEM 集成，STIX/TAXII 审计导出
- [ ] Gmail 推送 API + IMAP IDLE（取代轮询，消除检测延迟）
## 作者
**Lovely Professional University — 计算机科学与工程**
| 姓名 | 电子邮件 |
|---|---|
| Bokku Venkat Nanda Kishore | bvnkishore2004@gmail.com |
| Maddineni Raviteja | ravi9347783160@gmail.com |
| Minnekanti Durga Varun | varundurga80@gmail.com |
| G. Tharun Venkata Sai Kumar | tsai3822@gmail.com |
| Undela Yaswanth Kumar Reddy | undelayaswanthreddy143@gmail.com |
**指导教师：** Hariom，助理教授 — hariomsoniiimtgn@gmail.com
## 许可证
本项目采用 MIT 许可证授权。详见 [LICENSE](LICENSE)。
标签：AI风险缓解, AMSI绕过, Apex, DNS枚举, IMAP, PhishGuard, 人工智能, 分类模型, 反钓鱼, 可解释AI, 多阶段管道, 威胁检测, 数据泄露防护, 无GPU, 本地部署, 机器学习, 漏洞挖掘, 用户模式Hook绕过, 端点安全, 网络安全, 网络安全, 网络安全工具, 网络探测, 补丁管理, 逆向工具, 邮件安全, 钓鱼邮件检测, 隐私保护, 隐私保护