trevjacq/phishing-email-detector

# 钓鱼邮件检测器 一个基于 Python 的钓鱼邮件检测工具，结合了基于规则的启发式方法和朴素贝叶斯机器学习模型，用于识别钓鱼邮件——现在支持每条判决的 Claude AI 驱动的通俗语言解释、实时 Gmail 收件箱扫描，以及带颜色编码判决和标记分解的 HTML 扫描报告仪表板。 该项目由 Trevor Young 构建，作为一个网络安全作品集项目。 ## 功能 - 基于关键词和域名启发式的规则检测 - 基于朴素贝叶斯分类器的机器学习检测，训练数据超过 17,500 封真实钓鱼邮件 - 智能组合判决系统——通过权衡两层逻辑防止误报 - 通过 IMAP 的实时 Gmail 收件箱扫描 - 每封处理邮件的 JSON 扫描日志 - 自动生成的 HTML 报告仪表板，带颜色编码的判决和标记分解 - 机器学习模型的置信度百分比 - 详细标记输出，精确显示邮件被标记的原因 - Claude AI 驱动的通俗语言解释——每条判决都包含人类可读的摘要，说明邮件为何被标记以及用户应采取的操作 ## 项目结构 ``` phishing-detector/ │ ├── data/ # Dataset files (not included, see Setup) ├── logs/ # Auto-generated JSON scan logs ├── models/ # Saved ML model and vectorizer (auto-generated) ├── reports/ # Auto-generated HTML scan reports ├── utils/ │ ├── rules.py # Rule-based detection logic │ ├── ml_detector.py # Naive Bayes ML model (train + predict) │ ├── preprocessor.py # Text cleaning and preprocessing │ ├── email_fetcher.py # IMAP Gmail fetching │ ├── logger.py # JSON scan logger │ └── reporter.py # HTML report generator ├── main.py # Entry point ├── requirements.txt # Project dependencies └── README.md ``` ## 安装说明 ### 前置条件 - Python 3.10 或更高版本 - pip（随 Python 附带） - 已启用 2FA 的 Gmail 账户（用于实时收件箱扫描） ### 步骤 1 — 克隆仓库 ``` git clone https://github.com/YOUR_USERNAME/phishing-detector.git cd phishing-detector ``` ### 步骤 2 — 创建虚拟环境 ``` python -m venv venv ``` 激活环境： - **Windows:** `venv\Scripts\activate` - **Mac/Linux:** `source venv/bin/activate` ### 步骤 3 — 安装依赖 ``` pip install -r requirements.txt ``` ### 步骤 4 — 下载 NLTK 数据 ``` python -c "import nltk; nltk.download('stopwords'); nltk.download('punkt')" ``` ### 步骤 5 — 添加数据集 - 从 [Kaggle](https://www.kaggle.com/datasets/naserabdullahalam/phishing-email-dataset) 下载钓鱼邮件数据集 - 将文件重命名为 `emails.csv` - 将其放置在 `data/` 文件夹内 CSV 文件必须包含名为 `Email Text` 和 `Email Type` 的列，且取值分别为 `Safe Email` 和 `Phishing Email`。 ### 步骤 6 — 配置 Gmail（用于实时收件箱扫描） 1. 在 Gmail 账户中启用两步验证 2. 在 myaccount.google.com 生成应用密码 3. 打开 `utils/email_fetcher.py` 并填写： ``` EMAIL_ADDRESS = "your_email@gmail.com" APP_PASSWORD = "your_sixteen_char_app_password" ``` ## 用法 ``` python main.py ``` 这将： 1. 加载并清理数据集 2. 训练朴素贝叶斯分类器 3. 将模型保存到 `models/` 4. 在两个测试邮件上运行检测 5. 扫描实时 Gmail 收件箱中的未读邮件 6. 将所有结果记录到 `logs/scan_log.json` 7. 在 `reports/scan_report.html` 生成 HTML 报告 ## 示例输出 ``` Loading dataset... Cleaning text... Vectorizing text... Training model... --- Model Performance --- precision recall f1-score support Safe 0.98 0.97 0.98 1753 Phishing 0.97 0.98 0.97 1755 ========== DETECTION RESULTS (Test Emails) ========== --- Email 1 --- Subject : URGENT: Your account has been compromised! Sender : security@accounts-verify.xyz Rules : PHISHING (score: 27) ML Model : PHISHING (confidence: 89.21%) VERDICT : PHISHING --- Email 2 --- Subject : Your order has shipped Sender : orders@amazon.com Rules : SAFE (score: 0) ML Model : PHISHING (confidence: 83.41%) VERDICT : SAFE ``` ## 工作原理 ### 组合判决逻辑 | 条件 | 判决 | |---|---| | 规则得分 10 或更高 | PHISHING | | 机器学习置信度 85%+ 且预测为钓鱼 | PHISHING | | 规则得分 > 0 且机器学习预测为钓鱼 | PHISHING | | 规则得分为 0 且机器学习置信度低于 85% | SAFE | ### 基于规则的检测 | 检查 | 增加分数 | |---|---| | 检测到紧急语言 | 每匹配一次 +2 | | 检测到钓鱼关键词 | 每匹配一次 +2 | | 可疑发件人域名 | 每匹配一次 +3 | | 通用问候语（如 Dear Customer） | +2 | | 过多感叹号 | +1 | ### 机器学习检测 - 文本使用预处理器清洗 - 使用 5,000 个特征通过 TF-IDF 向量化 - 在 17,500+ 封邮件上训练的多项朴素贝叶斯分类器 - 模型和向量化器通过 pickle 保存到 `models/` ## 依赖项 | 包 | 用途 | |---|---| | scikit-learn | 朴素贝叶斯分类器和 TF-IDF 向量化器 | | pandas | 加载和操作数据集 | | numpy | 数值计算 | | nltk | 自然语言处理与停用词移除 | ## 路线图 - [x] 阶段 1 — 项目设置与环境配置 - [x] 阶段 2 — 基于规则的检测引擎 - [x] 阶段 3 — 朴素贝叶斯机器学习模型（训练与预测） - [x] 阶段 4 — 实时 IMAP Gmail 收件箱扫描 - [x] 阶段 5 — 组合评分、JSON 日志记录与 HTML 报告仪表板 - [ ] 阶段 6 — 置信度阈值调整与扩展规则集 - [ ] 阶段 7 — Web UI（Flask 或 Streamlit） ## 作者 **Trevor Young** - LinkedIn: [linkedin.com/in/trevor-young-b22831137](https://linkedin.com/in/trevor-young-b22831137) - 邮箱: trevjacq@gmail.com - CompTIA Security+ (SY0-701) 认证 ## 许可证 本项目开源，采用 MIT License 授权。

标签：AI解释, Apex, Claude AI, ETW劫持, Gmail扫描, HTML报告, IMAP, JSON日志, Python, 云计算, 假阳性抑制, 关键词匹配, 域名启发式, 投资组合项目, 文本预处理, 无后门, 日志记录, 朴素贝叶斯, 机器学习, 混合检测, 网络安全, 置信度评分, 规则引擎, 逆向工具, 钓鱼邮件检测, 隐私保护