kthnsolanki/Spam-Shield

# 🛡️ Spam Shield — 基于 AI 的消息与 URL 安全系统 ## 📌 概述 Spam Shield 是一个作为大学项目开发的全栈机器学习 Web 应用程序。它使用基于超过 35,000 个真实样本训练的朴素贝叶斯分类器，将 SMS 和电子邮件分类为 **垃圾邮件 (spam) 或正常邮件 (ham)**。该平台包括用户身份验证、三个扫描模块和个人扫描历史记录——所有这些都可以通过简洁的 Web 界面访问，无需任何外部工具。 ## ✨ 功能 | 功能 | 描述 | |---|---| | ✉️ **消息扫描器** | 将任何 SMS 或电子邮件分类为垃圾邮件/正常邮件，并附带置信度百分比和高亮显示的垃圾邮件关键词 | | 🔗 **URL 检查器** | 深度基于规则的分析——HTTPS 检查、域名解析、IP 查找、TLD 风险、子域名计数 | | 📂 **批量扫描器** | 上传 `.txt` 或 `.csv` 文件并一次性扫描数百条消息，显示完整结果表格 | | 🔐 **用户身份验证** | 使用 JWT token 和 bcrypt 哈希密码进行注册和登录 | | 🗄️ **扫描历史** | 每次扫描都会保存到个人的 SQLite 数据库中——可按类型过滤，可逐条记录删除 | | 🎨 **现代 UI** | 使用纯 HTML/CSS/JS 构建的响应式 Web 界面——无需框架 | ## 🧠 ML 架构 | 组件 | 详情 | |---|---| | 算法 | 多项式朴素贝叶斯 | | 特征提取 | TF-IDF Vectorizer (sklearn) | | 训练数据集 1 | Enron 电子邮件数据集 — 29,779 个样本 | | 训练数据集 2 | UCI SMS 垃圾邮件收集 — 5,572 个样本 | | 合并数据集 | 35,351 个样本（已打乱，80/20 拆分） | | 模型准确率 | 测试集上约为 98% | | 保存的文件 | `spam_model.pkl`, `tfidf_vectorizer.pkl` | ## 🗂️ 项目结构 ``` spam_shield/ │ ├── app.py # FastAPI backend — all routes and auth logic ├── model_util.py # ML prediction, spam word detection, URL analysis ├── database.py # SQLAlchemy models — User and ScanHistory tables │ ├── spam_model.pkl # Trained Naive Bayes model ├── tfidf_vectorizer.pkl # Fitted TF-IDF vectorizer ├── spam_shield.db # SQLite database (auto-created on first run) │ ├── templates/ │ └── index.html # Full frontend — auth, 3 modules, history view │ ├── comb_db.ipynb # Notebook: combining Enron + SMS datasets └── train_test.ipynb # Notebook: model training and evaluation ``` ## ⚙️ 安装与设置 ### 1. 克隆代码库 ``` git clone https://github.com/yourusername/spam-shield.git cd spam-shield ``` ### 2. 安装依赖 ``` pip install fastapi uvicorn jinja2 python-multipart scikit-learn pandas joblib sqlalchemy "passlib[bcrypt]" "bcrypt==4.0.1" PyJWT tldextract ``` ### 3. 确保存在这些文件 ``` spam_model.pkl tfidf_vectorizer.pkl templates/index.html ``` ### 4. 运行应用程序 ``` python app.py ``` ### 5. 在浏览器中打开 ``` http://localhost:8000 ``` ## 🚀 用法 1. **注册**一个新账户或使用现有凭据**登录** 2. 使用 **Message Scan** 选项卡粘贴任何可疑的 SMS 或电子邮件 3. 使用 **URL Checker** 选项卡分析任何 URL 的网络钓鱼指标 4. 使用 **Batch Scanner** 选项卡上传 `.txt` 或 `.csv` 文件进行批量分析 5. 点击顶部的 **History** 栏以查看、过滤和删除您过去的扫描记录 ## 🗃️ 数据库 Schema ### `users` 表 | 字段 | 类型 | 约束 | |---|---|---| | id | INT | PRIMARY KEY, AUTO INCREMENT | | username | VARCHAR(50) | NOT NULL, UNIQUE | | email | VARCHAR(120) | NOT NULL, UNIQUE | | hashed_password | VARCHAR | NOT NULL | | created_at | DATETIME | DEFAULT UTC NOW | ### `scan_history` 表 | 字段 | 类型 | 约束 | |---|---|---| | id | INT | PRIMARY KEY, AUTO INCREMENT | | user_id | INT | FOREIGN KEY → users.id | | scan_type | VARCHAR(20) | "message" / "url" / "batch" | | input_content | TEXT | NOT NULL | | result | VARCHAR(50) | spam / ham / SAFE / HIGH RISK | | confidence | FLOAT | NULLABLE | | extra_info | TEXT | NULLABLE (reserved) | | created_at | DATETIME | DEFAULT UTC NOW | ## 🛠️ 技术栈 | 层级 | 技术 | |---|---| | 后端 | Python, FastAPI, Uvicorn | | 机器学习 | Scikit-learn (朴素贝叶斯 + TF-IDF) | | 数据库 | 通过 SQLAlchemy ORM 访问的 SQLite | | 身份验证 | JWT (PyJWT) + bcrypt (passlib) | | 前端 | HTML5, CSS3, 原生 JavaScript | | URL 分析 | tldextract, socket (Python 标准库) | ## 📋 依赖项 ``` fastapi uvicorn jinja2 python-multipart scikit-learn pandas joblib sqlalchemy passlib[bcrypt] bcrypt==4.0.1 PyJWT tldextract ``` ## 📖 参考 - Metsis et al. (2006) — 使用朴素贝叶斯进行垃圾邮件过滤 - Almeida et al. (2011) — UCI SMS 垃圾邮件收集数据集 - Enron 电子邮件数据集 — 卡内基梅隆大学 - Scikit-learn 文档 — https://scikit-learn.org - FastAPI 文档 — https://fastapi.tiangolo.com ## 👨‍💻 作者 作为**大学项目 — 2026** 开发 计算机科学系 ## 📄 许可证 本项目仅供学术目的使用。

标签：Apex, AV绕过, FastAPI, Scikit-Learn, Web安全, 垃圾信息分类, 多模态安全, 威胁情报, 开发者工具, 数据可视化, 机器学习, 蓝队分析, 逆向工具