swarnim-dev/sentinel-ai

# Sentinel AI — 钓鱼预警系统 一款由 AI 驱动的浏览器扩展程序，利用可解释的机器学习实时检测钓鱼 URL 和可疑邮件。专为对网络安全感兴趣的学生打造。    ## 功能特性 | 功能 | 描述 | |---|---| | **URL 分类器** | 在 Kaggle "Phishing Website Detector" 数据集上训练的 RandomForest（11K+ 样本，97% 准确率） | | **邮件文本扫描器** | TF-IDF + Naive Bayes 模型检测邮件正文中的钓鱼语言 | | **头部异常检查** | 检测 SPF/DKIM 失败以及 From/Reply-To 不匹配 | | **SHAP 可解释性** | 每次预测都附带通俗易懂的英文理由（例如 "The URL uses a raw IP address instead of a domain name"） | | **网站拦截** | 钓鱼网站在**加载之前**即被拦截，并显示全屏插页式警告页面 | | **文件下载扫描器** | 下载时使用 6 层静态分析（魔数、熵值、可疑字符串等）自动扫描 10MB 以下的文件 | | **自动重训练反馈循环** | 模型从用户纠正中学习 —— 每积累 500 条报告后自动重新训练 | | **每周数字卫生报告** | 在本地跟踪浏览习惯，并显示包含安全评分、每日图表和标记域名的可视化仪表板 | ## 工作原理 ``` User visits a URL ↓ Background script intercepts BEFORE page loads ↓ Sends URL to FastAPI backend → RandomForest extracts 30 features → predicts ↓ ┌─ Safe → Page loads normally └─ Phishing → Page BLOCKED, interstitial shown with: • Risk percentage gauge • SHAP-generated plain-English reasons • "Go Back to Safety" / "I understand, proceed" buttons ↓ If user clicks "proceed" → feedback correction stored ↓ After 500 corrections → MODEL AUTO-RETRAINS • Merges original Kaggle data + user corrections • Retrains RandomForest (200 trees) • Hot-reloads model (no restart needed) • Clears feedback file, cycle repeats ``` ## 架构 ``` phishing_detector/ ├── backend/ │ ├── main.py # FastAPI server with all endpoints │ ├── train_url.py # Train URL model on Kaggle dataset │ ├── train_email.py # Train email text model │ ├── feedback_store.py # Feedback CSV storage + auto-retrain logic │ ├── models/ │ │ ├── url_model.py # 30-feature URL extractor + prediction │ │ ├── email_model.py # TF-IDF email classifier │ │ ├── headers_check.py # SPF/DKIM/Reply-To rule checks │ │ └── file_scanner.py # 6-layer static file analysis │ └── explain/ │ └── shap_explainer.py # SHAP explanations → plain English ├── extension/ │ ├── manifest.json # Chrome Manifest V3 │ ├── background.js # Intercepts navigation + logs scans + download scanner │ ├── content.js # Injects warning banners on pages │ ├── blocked.html / .js # Full-page interstitial for blocked sites │ ├── report.html / .js # Weekly Digital Hygiene Report dashboard │ ├── popup.html / .js # Extension popup dashboard │ └── styles.css # All styling └── data/ # Kaggle dataset (not in git) ``` ## 快速开始 ### 1. 克隆并安装依赖 ``` git clone https://github.com/swarnim-dev/sentinel-ai.git cd sentinel-ai python3 -m venv venv source venv/bin/activate pip install -r backend/requirements.txt ``` ### 2. 下载数据集 从 Kaggle 下载 [Phishing Website Detector](https://www.kaggle.com/datasets/eswarchandt/phishing-website-detector) 数据集，并将 `phishing.csv` 放入 `data/` 文件夹。 ### 3. 训练模型 ``` cd backend python train_url.py # Trains RandomForest URL classifier (~97% accuracy) python train_email.py # Trains TF-IDF email classifier ``` ### 4. 启动 API ``` cd backend uvicorn main:app --port 8000 ``` ### 5. 加载扩展程序 1. 在 Chrome/Brave/Edge 中打开 `chrome://extensions/` 2. 启用 **开发者模式** 3. 点击 **加载已解压的扩展程序** → 选择 `extension/` 文件夹 4. Sentinel 图标将出现在您的工具栏中 ## API 端点 | 方法 | 端点 | 描述 | |---|---|---| | `POST` | `/predict/url` | 扫描 URL → 风险评分 + SHAP 理由 | | `POST` | `/predict/email` | 扫描邮件正文 + 头部 → 风险评分 + 理由 | | `POST` | `/scan/file` | 上传文件（最大 10MB）进行静态恶意软件分析 | | `POST` | `/feedback` | 提交纠正（达到 500 条时触发重训练） | | `GET` | `/feedback/status` | 检查距离下次自动重训练的进度 | ### 示例 — 扫描 URL ``` curl -X POST http://127.0.0.1:8000/predict/url \ -H "Content-Type: application/json" \ -d '{"url": "http://192.168.1.1/paypal-login/secure"}' ``` ### 示例 — 检查重训练进度 ``` curl http://127.0.0.1:8000/feedback/status # → {"feedback_count": 42, "retrain_threshold": 500, "progress_percent": 8.4} ``` ## 自动重训练反馈循环 模型通过用户反馈随时间推移而改进： 1. 当用户在被拦截的页面上点击 **"I understand, proceed"** 时，系统会存储该 URL 的 30 个提取特征以及纠正信息 2. 纠正记录在 `backend/feedback_log.csv` 中累积 3. 当达到 **500 条纠正** 时，系统会自动： - 将原始的 11K Kaggle 样本与 500 条用户标记的纠正合并 - 重新训练 RandomForest 分类器（200 棵树） - 保存更新后的模型并热加载（无需重启服务器） - 清除反馈文件 —— 循环重置，等待下一个 500 条 ## 每周数字卫生报告 点击扩展弹窗中的 **"View Weekly Report"** 可查看： - **统计卡片** — 总扫描次数、安全站点、拦截的威胁、独立域名数 - **安全评分** — 颜色编码的环形图（优秀 / 良好 / 一般 / 较差） - **每日柱状图** — 最近 7 天的安全与钓鱼网站分类明细 - **标记最多的域名** — 您遇到的风险最高的网站 所有数据**存储在本地 Chrome 存储中** —— 不会发送到任何服务器。 ## 文件下载扫描器 您下载的每个文件（10MB 以下）都会通过 **6 个分析层**自动扫描： | 层级 | 检测内容 | |---|---| | **危险扩展名** | `.exe`, `.bat`, `.ps1`, `.vbs`, `.scr`, `.msi`, `.jar`, `.sh` 等 | | **双重扩展名** | 像 `invoice.pdf.exe` 这样伪装真实类型的文件 | | **魔数分析** | 检测文件扩展名与实际内容之间的不匹配（例如一个实际上是 `.exe` 的 `.pdf` 文件） | | **熵值分析** | 高香农熵 值表明存在加壳/加密的恶意软件 | | **可疑字符串** | PowerShell 命令、base64 解码、`eval()`、注册表编辑、反向 shell | | **Office 宏指标** | Office 文件中的 VBA 宏、`AutoOpen`、`Shell`、`CreateObject` | 扫描结果会在下载完成后立即以 **Chrome 通知** 的形式显示。 ``` # Manual test via API curl -X POST http://127.0.0.1:8000/scan/file -F "file=@suspicious_file.exe" ``` ## 技术栈 - **后端:** Python, FastAPI, scikit-learn, SHAP, Pandas - **ML 模型:** RandomForest (URL), Naive Bayes + TF-IDF (邮件) - **扩展程序:** JavaScript, Chrome Manifest V3 - **数据集:** [Kaggle Phishing Website Detector](https://www.kaggle.com/datasets/eswarchandt/phishing-website-detector) ## 许可证 MIT

标签：Apex, AV绕过, FastAPI, Manifest V3, Python, SHAP, URL分类, Web安全, XAI, 云安全监控, 人工智能, 反钓鱼, 可解释AI, 实时防护, 教育安全工具, 数据可视化, 无后门, 机器学习, 浏览器扩展, 用户模式Hook绕过, 网络威胁防御, 网络安全, 蓝队分析, 逆向工具, 邮件安全, 钓鱼检测, 随机森林, 隐私保护, 静态分析