AryanPawr/Phishguard

# PhishGuard PhishGuard 是一个全栈网络钓鱼检测平台，结合了浏览器扩展、FastAPI 后端、结构化机器学习流水线、品牌冒充检测、本地威胁情报以及受 JWT 保护的分析仪表板。它被设计为一个网络安全组合项目，用于展示跨浏览器、后端和机器学习层的实用检测工程能力。 ## 概述 PhishGuard 检测 Gmail、Outlook Web 以及通用网页渲染邮件中的可疑邮件内容。扩展程序提取标准化消息数据，应用轻量级本地启发式规则，屏蔽敏感内容，并在传输前提交隐私缩减后的负载。后端执行结构化特征提取、模型推理、冒充检测和加权分数融合，最后返回风险评估结果。管理遥测信息通过仪表板和 SIEM 友好格式暴露。 ## 核心功能 - 用于 Gmail、Outlook Web 和通用邮件渲染页面的 Manifest V3 浏览器扩展 - 本地客户端侧启发式规则，用于识别紧急语言、可疑链接、伪造和域名不匹配 - 提交前优先进行隐私保护的内容屏蔽 - 带请求验证、评分、持久化和 JWT 保护管理路由的 FastAPI 后端 - 结构化的网络钓鱼特征提取流水线 - 基于 TF-IDF 和逻辑回归的基线机器学习架构，支持回退推理 - 品牌冒充和相似域名检测 - 基于 React + Tailwind 的分析仪表板 - 用于下游安全工作流程的 SIEM JSON 导出 - 威胁情报注册表和网络钓鱼规则 - 对后端、特征提取、评分、机器学习训练和扩展清单安全性进行测试 ## 架构 ``` extension/ Browser extraction, local heuristics, masking, cache, UI banner backend/ FastAPI API, feature extraction, ML inference, scoring, persistence dashboard/ React + Tailwind admin interface intelligence/ Brand registry, phishing rules, feed notes shared/ JSON schemas for request/response/event contracts infrastructure/ Docker Compose and nginx example config tests/ API, ML, scoring, feature extraction, and extension tests docs/ Architecture, security, ML pipeline, SIEM, deep-dive notes ``` ## 检测流程 1. 用户在 Gmail、Outlook Web 或其他支持的网络渲染邮件界面中打开一封邮件。 2. 扩展程序提取发件人、显示名称、主题、正文文本、链接和上下文信息。 3. 本地启发式规则对明显的网络钓鱼信号进行评分，并在传输前屏蔽个人身份信息（PII）。 4. 后端验证请求并再次应用服务端屏蔽。 5. 从文本、链接、域名和可用 HTML 中提取结构化特征。 6. 后端运行机器学习推理、冒充检测和信誉逻辑。 7. 加权评分引擎生成最终分类和解释。 8. 扩展程序渲染实时警告横幅。 9. 后端存储匿名化遥测数据，用于仪表板分析和 SIEM 导出。 ## 技术栈 ### 扩展 * Manifest V3 * JavaScript * 内容脚本 * 后台服务工作线程 * 自定义横幅 UI ### 后端 * FastAPI * Pydantic * SQLAlchemy * 本地开发用的 SQLite * JWT 认证 * 进程内速率限制 ### 机器学习 * scikit-learn * TF-IDF 向量化 * 数值结构化特征 * 逻辑回归 * joblib 模型工件加载 ### 仪表板 * React * Vite * Tailwind CSS ## 安装指南 ### 先决条件 在开始设置前安装以下内容： * Python 3.11+ 或 3.12 * Node.js 18+ 和 npm * Git * Chromium 浏览器或 Firefox ## 后端设置 ``` cd backend python -m venv .venv source .venv/bin/activate pip install -r requirements.txt cp .env.example .env uvicorn app.main:app --reload ``` 后端运行在： ``` http://localhost:8000 ``` 健康检查： ``` curl http://localhost:8000/health ``` ## 仪表板设置 ``` cd dashboard npm install cp .env.example .env npm run dev ``` 打开： ``` http://localhost:5173 ``` 默认开发凭据： ``` username: admin password: phishguard-admin ``` 在使用项目超出本地开发环境之前，请在 `backend/.env` 中修改这些配置。 ## 扩展设置 ### Chrome / Chromium 1. 打开 `chrome://extensions` 2. 启用开发者模式 3. 点击 **加载已解压的扩展程序** 4. 选择 `extension/` 文件夹 ### Firefox 1. 打开 `about:debugging#/runtime/this-firefox` 2. 点击 **加载临时附加组件** 3. 选择 `extension/manifest.json` 扩展程序将在打开支持页面时调用本地后端并显示风险横幅。 ## 生产集成 当前部署端点： - 后端 URL：`https://phishguard-backend-anw5.onrender.com` - 仪表板 URL：`https://phishguard-dashboard.vercel.app` - 仪表板环境变量：`VITE_API_BASE_URL=https://phishguard-backend-anw5.onrender.com/api` - 后端 CORS 环境变量：`PHISHGUARD_CORS_ORIGINS=https://phishguard-dashboard.vercel.app` - 扩展默认 API URL：`https://phishguard-backend-anw5.onrender.com/api` 后端从 `PHISHGUARD_CORS_ORIGINS` 读取 CORS 源；在本地运行仪表板时，仅将 localhost 值保留在本地 `.env` 文件中。 ## 运行测试套件 从项目根目录： ``` pytest ``` 如果仅需要后端测试： ``` cd backend source .venv/bin/activate cd .. pytest tests ``` ## 模型训练 默认模型路径为： ``` backend/app/services/ml_engine/models/phishing_model.pkl ``` 已提交的模型工件可视为占位符或引导工件。如果无可用的有效训练模型，后端将回退到确定性评分行为。 从 CSV 数据集训练基线模型： ``` cd backend source .venv/bin/activate python -m app.services.ml_engine.train --dataset ../data/phishing_training.csv ``` 预期数据集模式： * 一个类似文本的列，例如 `text`、`body`、`body_text`、`email`、`message`、`content` 或 `url` * 一个类似标签的列，例如 `phishing`、`malicious`、`spam`、`safe`、`legitimate`、`ham`、`1` 或 `0` ## 评分策略 最终分数结合多个独立信号： ``` final_score = 0.30 * ml_probability + 0.25 * impersonation_score + 0.20 * heuristic_score + 0.15 * link_reputation + 0.10 * domain_registry_mismatch ``` 这种多信号设计通过结合模型输出与确定性安全信号，提升了系统的弹性和可解释性。 ## 安全控制 * 不在持久化遥测中存储原始邮件 * 发件人、主题和样本标识符以哈希形式存储 * 提交前在客户端进行屏蔽 * 服务端再次应用屏蔽 * 受 JWT 保护的管理和 SIEM 路由 * 严格的 CORS 配置 * 输入大小限制和请求验证 * 本地速率限制以防止 API 滥用 * 扩展和 nginx 示例配置中的 CSP 控制 ## 阶段 2：模型训练与检测成熟度 阶段 1 建立了平台与基础检测流水线。阶段 2 应专注于提升模型质量、数据集真实性和评估严谨性。 ### 阶段 2 目标 * 用真正训练过的模型替换占位符或回退行为 * 提升网络钓鱼与良性数据集质量 * 扩展结构化特征以实现更好的泛化 * 评估多个分类器 * 测量精确率、召回率、F1、ROC-AUC 和假阳性率 * 添加可重现的评估与模型版本管理 * 为机器学习层准备基于 Transformer 的升级 ### 建议的阶段 2 工作计划 #### 1. 构建更优的训练数据集 从以下来源创建 curated 数据集： * 网络钓鱼邮件数据集 * 合法邮件与新闻邮件样本 * URL 情报来源，如 PhishTank 或 OpenPhish * 用于品牌冒充和相似域名的人工标注样本 目标应包含： * 网络钓鱼样本 * 良性事务邮件 * 良性安全告警 * 新闻邮件和营销邮件 * 品牌冒充示例 * 欺骗性锚文本示例 #### 2. 规范化与一致标注 将标签标准化为： * `1` 表示网络钓鱼或恶意 * `0` 表示良性或安全 规范化以下内容： * 发件人域名字段 * 正文文本格式 * 提取的链接 * 编码伪影 * 重复记录 #### 3. 扩展特征工程 在现有流水线基础上改进： * 更佳的相似域名特征 * 基于公共后缀的域名解析 * 更健壮的锚点不匹配逻辑 * 重定向链指示 * 语言特定的网络钓鱼短语集合 * 改进的可疑 TLD 评分 * 可选的 HTML 派生的表单和隐藏元素信号 #### 4. 评估多个基线 至少比较以下方法： * 逻辑回归 * 线性 SVM * 在结构化特征子集上的随机森林或梯度提升 根据网络钓鱼召回率和平衡的假阳性控制保留最佳模型。 #### 5. 添加完善的评估输出 阶段 2 应保存： * 模型版本* 训练日期 * 数据集来源 * 评估指标 * 混淆矩阵 * 特征重要性或系数摘要（如果可能） 建议的工件布局： ``` backend/app/services/ml_engine/models/ backend/app/services/ml_engine/reports/ backend/app/services/ml_engine/experiments/ ``` #### 6. 添加可重现的实验脚本 包含用于以下功能的脚本： * 训练 * 评估 * 模型比较 * 导出最佳工件 这将使机器学习部分在 GitHub 和面试中更具优势。 #### 7. 为 Transformer 升级做准备 一旦结构化基线稳定，阶段 2.5 或阶段 3 可以探索： * DistilBERT 微调 * 结合结构化特征的 Transformer 嵌入 * ONNX 运行时推理 * 传统与 Transformer 输出之间的校准 当前架构已经支持这一路径，因为模型推理已被视为可替换的后端组件。 ## 建议的未来改进 * 使用 PostgreSQL 替代 SQLite 用于部署 * 基于 Redis 的分布式速率限制 * 基于角色的访问控制（RBAC）和多用户管理 * 从仪表板到模型改进的反馈闭环 * 用于误报和误判的分析师工作流 * 更强的 Firefox 消息兼容性加固 * 可选威胁源摄取任务 * OCR 或基于图像的钓鱼检测 * 二维码网络钓鱼检测 * 云部署和扩展商店打包 ## 项目状态 当前状态： * 端到端脚手架完整 * 包含扩展、后端、仪表板、测试和文档 * 基础机器学习流水线已就绪 * 已准备好基于数据集的阶段 2 训练和评估 ## 仓库主题 推荐的 GitHub 主题： * 网络安全 * 网络钓鱼检测 * 浏览器扩展 * FastAPI * 机器学习 * 威胁情报 * React * 检测工程 ## 许可证 MIT 许可证。

标签：Apex, AV绕过, FastAPI, Gmail, JWT认证, Manifest V3, Outlook Web, React仪表盘, SIEM导出, Tailwind, TF-IDF, 云计算, 全栈安全, 前端仪表盘, 可疑链接检测, 后端API, 品牌冒充检测, 域名不匹配检测, 威胁情报, 威胁情报注册表, 开发者工具, 数据脱敏, 机器学习, 查仿冒域名, 测试覆盖, 浏览器扩展, 浏览器数据采集, 特征工程, 端点安全, 紧急语言检测, 结构化评分, 网络安全, 网络安全项目, 网络钓鱼防御, 补丁管理, 规则引擎, 请求拦截, 通用网页邮箱, 逻辑回归, 钓鱼检测, 隐私保护