eshaansaini2004/phish-shield-ext

# PhishShield 一个实时分析链接并在点击恶意内容前发出警告的 Chrome 扩展。为所有用户设计，尤其适合那些并非互联网原住民的人群。 悬停在任意链接上即可获得即时绿色、黄色或红色徽章。完全可通过设置页面进行配置，以便调整启用的检测层或将可信域名加入白名单。 ## 功能 **每次悬停链接时都会运行四层分析：** ### 第一层 — URL 启发式检测（即时，无需联网） 在加载任何内容前先检查 URL 本身： - 基于 IP 的 URL（`http://192.168.1.1/login`） - 子域名中的品牌冒充（`paypal.com.evil.com`） - 品牌拼写错误（`paypa1.com`、`g00gle.com`） - Unicode 相似字符（е 与 e、а 与 a） - 可疑关键词（`/verify-account`、`/confirm-password`） - URL 缩短服务（bit.ly、tinyurl 等） - 可疑 TLD（`.tk`、`.ml`、`.cf`、`.gq`） - 重复扩展名（`invoice.pdf.exe`） - 重定向链（`?url=`、`?goto=`） - 以及其他（总计 14 项检查） ### 第二层 — 机器学习分类器（即时，无需联网） 一个神经网络（MLP：18 输入 → 32 → 16 → 1）在浏览器中完全运行，不与服务器往返。它提取 18 个 URL 特征（熵、子域名深度、数字密度、TLD 风险等），并返回钓鱼概率分数。该分数与启发式得分融合（45% 启发式 + 55% 机器学习），使两层相互增强。若 ML 置信度达到 60% 或更高，会在弹出窗口中明确标记。 模型使用 scikit-learn 训练，并导出为紧凑的 JSON 权重文件（约 24 KB）。要重新训练：`cd train_model && python train.py` ### 第三层 — 页面分析（在页面加载后运行） 检查当前页面是否存在钓鱼迹象： - HTTP 页面中的密码输入框 - 提交到其他域名的表单 - 加载外部内容的隐藏 iframe - 伪造的病毒/系统警告弹窗 - 页面标题中的品牌名称与实际域名不匹配 - 禁用了右键（常见于钓鱼页面） - Meta 刷新重定向 ### 第四层 — 下载拦截 在危险文件运行前拦截： - 高风险文件类型（`.exe`、`.bat`、`.ps1`、`.vbs` 等） - MIME 类型不匹配（文件声称是 PDF，实际是 .exe） - 重复扩展名（`document.pdf.exe`） - 非用户点击触发的自动下载 - 通用钓鱼文件名（`invoice.exe`、`update.exe`） ### 威胁情报 API（需要配置） 配置后，扩展还会检查： - **Google Safe Browsing** — Google 的已知恶意 URL 数据库 - **PhishTank** — 众包的钓鱼 URL 数据库 - **域名年龄** — 标记新注册的域名（常见于钓鱼活动） 请参阅 [SETUP.md](./SETUP.md) 了解如何启用这些功能。 ### 设置页面 右键点击扩展图标 → **选项**，即可： - 开启或关闭任意分析层（URL 启发式、机器学习、DOM、下载） - 将域名加入白名单 — 白名单站点将绕过所有检查并立即返回安全 - 通过 `chrome.storage.sync` 在 Chrome 配置文件间同步设置 ### 举报为钓鱼 弹出窗口中分析完成后会显示一个小的 **⚑ 举报** 按钮。点击它将： - 在新标签页中打开 PhishTank 提交页面，以便向社区举报 - 将报告记录到本地（存储在 chrome.storage 的 `phishshield_reports` 中） ## 界面表现 悬停在任意网页的链接上时，光标附近会出现一个小药丸形徽章： - **绿色** — 看起来安全 - **黄色** — 可疑，值得再看一眼 - **红色** — 多个危险标志，不要点击 点击工具栏中的扩展图标，可查看完整分析结果：风险分数、具体触发项，以及通俗易懂的解释。 ## 已知限制 ### Google Docs、Figma 等类似应用 这些应用不使用标准的 HTML `` 链接。它们在画布层上渲染所有内容并使用自定义点击处理程序，因此扩展无法挂钩到单个链接。悬停提示不会在这些应用内显示。 不过，扩展现在通过 `webNavigation.onCommitted` 检测所有顶级导航 — 因此通过这些应用导航到危险 URL 时，只要分数达到 70 或更高，仍会显示通知横幅。 仅影响悬停提示：Google Docs、Sheets、Slides、Figma、Notion（部分）。 ### iframe 跨域 iframe 中的内容（内嵌广告等）由于浏览器安全策略无法被内容脚本访问，因此这些 iframe 内的链接不会显示提示。 ### URL 缩短服务 扩展会将已知缩短域名（bit.ly、tinyurl 等）标记为可疑，因为真实目标被隐藏。若未部署 Cloudflare Worker，则无法跟随重定向。 ## 快速开始 ``` npm install npm run build ``` 然后在 Chrome 中打开：`chrome://extensions` → 开发者模式 → 加载已解压的扩展程序 → 选择 `dist/` 如需包含 API 密钥的完整配置说明，请参阅 [SETUP.md](./SETUP.md) ## 项目结构 ``` src/ analysis/ urlAnalysis.js # Layer 1 — 14 URL heuristic checks mlAnalysis.js # Layer 2 — in-browser MLP inference (18 features) domAnalysis.js # Layer 3 — 10 DOM/page checks downloadAnalysis.js # Layer 4 — 7 download checks background/ background.js # Service worker, orchestrates all layers api.js # Cloudflare Worker API client content/ content.js # Hover tooltips, page analysis trigger popup/ App.jsx # Main popup UI (includes report button) RiskBadge.jsx # Big green/yellow/red status badge ScoreBar.jsx # Risk score 0–100 bar FlagList.jsx # Plain-English list of what was flagged HelpSection.jsx # Collapsible explainer for non-technical users options/ App.jsx # Settings page (layer toggles + whitelist) main.jsx # React entry for options page public/ model/ weights.json # Trained MLP weights + scaler params (~24 KB) cloudflare-worker/ worker.js # Backend proxy for threat intelligence APIs train_model/ train.py # scikit-learn training script → exports weights.json requirements.txt # pip deps (scikit-learn, pandas, numpy, requests) ``` ## 技术栈 - Chrome 扩展清单 V3 - React + Vite（弹出窗口 UI） - scikit-learn MLP → 权重导出为 JSON，纯 JavaScript 前向传播（无需推理库） - Cloudflare Workers（无服务器后端，免费额度） - Google Safe Browsing API v4 - PhishTank API