rocky-2904/NeuroPhish

# 🛡️ NeuroPhish — 实时钓鱼邮件检测系统 NeuroPhish 是一个端到端的钓鱼邮件检测 pipeline，它将 **NLP 特征工程**与 **Scikit-learn 分类模型**以及 交互式的 **Streamlit 威胁情报仪表板**结合在一起。它的构建旨在 展示一种实用的、生产级的邮件威胁检测方法——从原始文本到实时风险评分。 ## ✨ 功能 - **混合特征工程** — 将 TF-IDF 文本向量化与 人工设计的钓鱼信号特征（紧急性语言、可疑 关键词、URL 模式、基于 IP 的链接、发件人域名异常）相结合。 - **RandomForest 分类 pipeline**，包含训练/测试评估、 ROC-AUC、精确率/召回率以及混淆矩阵报告。 - **交互式 Streamlit 仪表板**，包含 5 个实时面板： 1. 实时邮件风险评分 2. 模型性能 KPI 3. 混淆矩阵与 ROC 曲线 4. 特征重要性（“为什么被标记？”） 5. 带有类别平衡可视化的数据集浏览器 - **可解释的风险信号** — 每封被标记的邮件都会显示*为什么*被 标记（例如 `num_urgent_words`、`sender_domain_suspicious`、`num_urls`）。 - 包含**合成数据集生成器**，因此项目无需任何外部下载即可 立即运行——只需几分钟即可替换为真实世界的数据集 （参见下方的[使用真实数据集](#using-a-real-dataset)）。 ## 🏗️ 架构 ``` Email (subject, body, sender) │ ▼ ┌─────────────────────┐ │ Text Preprocessing │ lowercasing, whitespace normalization └──────────┬───────────┘ ▼ ┌─────────────────────────────┐ │ Feature Engineering │ │ • TF-IDF (1-2 grams) │ │ • Urgency / keyword counts │ │ • URL & IP-link detection │ │ • Sender domain heuristics │ └──────────┬───────────────────┘ ▼ ┌─────────────────────┐ │ RandomForest Classifier │ → risk score (0-100%) + label └──────────┬───────────┘ ▼ ┌─────────────────────────────┐ │ Streamlit Threat Dashboard │ └───────────────────────────────┘ ``` ## 📂 项目结构 ``` NeuroPhish/ ├── app.py # Streamlit dashboard (entry point) ├── requirements.txt ├── src/ │ ├── data_generator.py # Synthetic phishing/legit email generator │ ├── feature_engineering.py # TF-IDF + handcrafted feature extraction │ ├── train_model.py # Model training + evaluation │ └── predict.py # Single-email inference ├── data/ │ └── emails.csv # Generated dataset (created by data_generator.py) ├── models/ # Trained model artifacts (created by train_model.py) └── notebooks/ # (optional) exploratory analysis ``` ## 🚀 快速开始 ### 1. 克隆并安装依赖 ``` git clone https://github.com/rocky-2904/NeuroPhish.git cd NeuroPhish python -m venv venv source venv/bin/activate # Windows: venv\Scripts\activate pip install -r requirements.txt ``` ### 2. 生成数据集（或使用已包含的数据集） ``` python src/data_generator.py --n_per_class 300 --out data/emails.csv ``` ### 3. 训练模型 ``` python src/train_model.py --data data/emails.csv --model_dir models ``` 这会打印准确率/精确率/召回率/F1/ROC-AUC，并将模型、 vectorizer 和指标保存到 `models/`。 ### 4. 启动仪表板 ``` streamlit run app.py ``` 打开 Streamlit 打印的本地 URL（通常是 `http://localhost:8501`）。 ## 🧪 使用真实数据集 内置的 `data_generator.py` 会生成一个合成的、基于模板的 数据集，以便项目开箱即用——这对于演示很有用，但不能 替代真实世界的数据。要使用真实邮件进行训练： 1. 下载一个公开的钓鱼数据集，例如 [Kaggle 钓鱼邮件数据集](https://www.kaggle.com/datasets) 或 [Nazario 钓鱼语料库](https://monkey.org/~jose/phishing/)。 2. 将其格式化为包含以下列的 CSV：`subject`、`body`、`sender`、`label` （`1` = 钓鱼，`0` = 正常）。 3. 将训练指向它： python src/train_model.py --data path/to/real_emails.csv ## 🛠️ 技术栈 | 层级 | 工具 | |---------------------|-------------------------------------------| | 语言 | Python 3.10+ | | NLP / 特征工程 | Scikit-learn `TfidfVectorizer`，基于正则的启发式规则 | | 模型 | RandomForestClassifier (Scikit-learn) | | 仪表板 | Streamlit, Matplotlib | | 数据 | Pandas, NumPy, SciPy (稀疏矩阵) | ## 📈 路线图 / 扩展想法 - [ ] 添加 `.eml` 文件上传器，用于对真实的收件箱导出进行评分 - [ ] 将 RandomForest 替换为微调过的 transformer（例如 DistilBERT）并进行比较 - [ ] 添加基于 SHAP 的单封邮件可解释性 - [ ] 部署到 Streamlit Community Cloud 并提供公开的演示链接 - [ ] 添加用于 Gmail/Outlook 分类处理的浏览器扩展前端 ## 👤 作者 **Raakesh Kumar S** 专注于网络安全的 CSE 学生 | 拥有 RHCSA 认证 [LinkedIn](https://linkedin.com/in/raakesh-kumar-s-b906232b7) · [GitHub](https://github.com/rocky-2904) ## 📄 许可证 该项目基于 MIT 许可证授权——详见 [LICENSE](LICENSE)。

标签：Apex, Kubernetes, Scikit-learn, Streamlit, 机器学习, 网络安全, 访问控制, 逆向工具, 钓鱼检测, 隐私保护