OrAtias99/phish-scan

# Phish Scan ### 邮件钓鱼检测系统与 Gmail 插件 # Phish Scan ### 邮件钓鱼检测系统与 Gmail 插件 ## 1. 检测模型如何工作 Phish Scan 采用双层检测架构，结合基于规则的启发式方法与机器学习模型，将邮件分类为 **PHISHING（钓鱼）**、**SUSPICIOUS（可疑）** 或 **SAFE（安全）**。 ### 1.1 启发式层（主要） 启发式引擎对解析后的邮件运行一组规则函数。每个规则返回一个带有严重程度和权重的信号。当前实现的规则包括： - `URGENT_LANGUAGE` – 检测施压词汇（“urgent”、“act now”、“expires”） - `SENSITIVE_INFO_REQUEST` – 检测对密码、OTP、信用卡、SSN 的请求 - `BEC_WIRE_TRANSFER` – 检测商业邮件入侵模式（IBAN、转账、新账户） - `BEC_IMPERSONATION` – 检测高管冒充（CEO、CFO、董事） - `BEC_SECRECY_REQUEST` – 检测要求保持通信秘密 - `CALLBACK_PHISHING` – 检测电话号码 + 未经授权的收费语言 - `GIFT_CARD_SCAM` – 检测购买礼品卡并发送代码的请求 - `SEXTORTION` – 检测摄像头威胁、比特币钱包要求、曝光威胁 - `BRAND_DOMAIN_MISMATCH` – 检测内容中的品牌名称与发件人域名不匹配 - `URL signals` – IP 主机、URL 缩短器、punycode、非 HTTPS、可疑 TLD、@ 符号 ### 1.2 机器学习层（次要） 随机森林分类器在标记的邮件数据集上进行训练。它从每封邮件中提取 18 个数值特征，包括： - 紧迫词汇数、敏感词汇数 - 正文长度（对数缩放）、感叹号数量、大写比例 - 基于 URL 的特征：IP 主机、缩短器、HTTPS、子域名数量、TLD 可疑度、punycode - 品牌不匹配信号 机器学习模型使用以下数据集进行训练： - HuggingFace 钓鱼邮件数据集（`zefang-liu/phishing-email-dataset`） - 短信垃圾邮件/正常短信数据集（`dataset_SMS_spam_ham.tsv`） - 合成备用示例（始终激活） ### 1.3 分数融合 最终分数是两层加权的混合： ``` final_score = 0.8 × heuristic_score + 0.2 × ml_score ``` 分类阈值： | 分数范围 | 标签 | |----------|------| | 71 – 100 | 🚨 PHISHING | | 31 – 70 | ⚠️ SUSPICIOUS | | 0 – 30 | ✅ SAFE | ### 1.4 客户端遥测（可选） Gmail 插件可以可选地报告客户端检测到的可疑链接数量。此信号只能 **增加** 怀疑分数，绝不会降低。它上限为 20 个链接，以防止滥用。 ## 2. 如何安装并使用 Gmail 插件 ### 2.1 先决条件 - 已安装 Python 3.11+ - 具有 Gmail 访问权限的 Google 账户 - 用于暴露本地后端的 ngrok（免费账户） - 已克隆的 phish-scan 仓库 ### 2.2 步骤 1 – 设置后端 从项目根目录开始： ``` # Install dependencies .venv-314\Scripts\pip install scikit-learn pandas fastapi uvicorn pydantic python-dotenv httpx # Train the ML model $env:PYTHONPATH = "." python -m detector.detector.ml.train # Start the backend server $env:PHISHSCAN_API_KEY = "my-secret-key" .venv-314\Scripts\python.exe -m uvicorn backend.service.main:app --reload --port 8000 ``` ### 2.3 步骤 2 – 使用 ngrok 暴露后端 ``` ngrok http 8000 ``` 复制显示的 HTTPS URL（例如 `https://abc123.ngrok-free.app`）。 ### 2.4 步骤 3 – 部署 Gmail 插件 1. 打开 [https://script.google.com](https://script.google.com) 并创建一个名为 **“Phish Scan”** 的新项目。 2. 上传仓库中 `addon/` 目录下的所有 `.gs` 文件。 3. 使用正确的 OAuth 范围更新 `appsscript.json`（参见 `addon/appsscript.json`）。 4. 进入 **项目设置 → 脚本属性** 并设置： - `BACKEND_BASE_URL` = `https://abc123.ngrok-free.app` - `BACKEND_API_KEY` = `my-secret-key` 5. 点击 **部署 → 测试部署 → Google Workspace 插件 → 安装**。 6. 打开 Gmail，打开任意邮件，并点击右侧边栏中的 **Phish Scan** 图标。 ### 2.5 使用插件 安装后，插件可在 Gmail 中任意打开的邮件中使用： 1. 在 Gmail 中打开一封邮件 2. 点击右侧边栏中的 **Phish Scan** 图标 3. 点击 **“Scan for Phishing”** 4. 查看结果：标签（PHISHING / SUSPICIOUS / SAFE）、分数（0–100）和详细原因 ## 3. 限制与未来改进 ### 3.1 当前限制 - 机器学习模型在有限数据集上训练，可能无法泛化到所有钓鱼风格 - 后端在本地运行，Gmail 插件需要 ngrok 或云部署才能正常工作 - 不支持 HTML 邮件解析——仅分析纯文本正文 - 模型不分析邮件附件 - ngrok 免费层级会生成新的 URL，需要手动更新脚本属性 - Google Apps Script 插件尚未经过 Google 验证（仅限个人/测试使用） ### 3.2 未来改进 - 在包括 BEC、sextortion 和 callback phishing 示例的更大、更多样化的钓鱼数据集上进行训练 - 添加 HTML 邮件正文解析以提取隐藏 URL 和混淆文本 - 将后端部署到云提供商（例如 Google Cloud Run）以获得永久 URL - 实现反馈循环——允许用户标记误报/漏报以改进模型 - 添加附件扫描支持（PDF、Office 文档） - 扩大品牌冒充检测覆盖更多公司 - 添加对希伯来语等语言的多语言钓鱼检测支持 - 提交 Gmail 插件以通过 Google 验证并移除安全警告 ## 4. 项目结构 ``` phish-scan/ ├── detector/ │ ├── heuristics/ │ │ ├── rules.py # Rule-based signal detection │ │ └── scoring.py # Signal aggregation and scoring │ ├── ml/ │ │ ├── featurize.py # Feature extraction for ML │ │ ├── model_io.py # Model load/save with caching │ │ └── train.py # Model training script │ ├── parsing/ │ │ ├── email_parser.py # Email normalization │ │ └── url_features.py # URL feature extraction │ ├── artifacts/ │ │ ├── model.pkl # Trained ML model │ │ ├── phishing_email.csv │ │ └── dataset_SMS_spam_ham.tsv │ └── pipeline.py # Main analysis pipeline ├── backend/ │ └── service/ │ ├── main.py # FastAPI app entry point │ ├── api/ │ │ ├── routes.py # POST /scan endpoint │ │ └── middleware.py # API key authentication │ └── core/ │ └── config.py # Settings and configuration ├── addon/ │ ├── appsscript.json # Add-on manifest and OAuth scopes │ └── src/ │ ├── handlers/ │ │ ├── scan_action.gs # Main scan handler │ │ └── homepage.gs # Homepage trigger │ ├── ui/ │ │ └── cards.gs # Gmail UI card builder │ ├── api_client/ │ │ └── backend_client.gs # HTTP client for backend │ └── gmail/ │ └── fetch_message.gs # Gmail message fetcher └── README.md ``` ## 1. 检测模型如何工作 Phish Scan 采用双层检测架构，结合基于规则的启发式方法与机器学习模型，将邮件分类为 **PHISHING（钓鱼）**、**SUSPICIOUS（可疑）** 或 **SAFE（安全）**。 ### 1.1 启发式层（主要） 启发式引擎对解析后的邮件运行一组规则函数。每个规则返回一个带有严重程度和权重的信号。当前实现的规则包括： - `URGENT_LANGUAGE` – 检测施压词汇（“urgent”、“act now”、“expires”） - `SENSITIVE_INFO_REQUEST` – 检测对密码、OTP、信用卡、SSN 的请求 - `BEC_WIRE_TRANSFER` – 检测商业邮件入侵模式（IBAN、转账、新账户） - `BEC_IMPERSONATION` – 检测高管冒充（CEO、CFO、董事） - `BEC_SECRECY_REQUEST` – 检测要求保持通信秘密 - `CALLBACK_PHISHING` – 检测电话号码 + 未经授权的收费语言 - `GIFT_CARD_SCAM` – 检测购买礼品卡并发送代码的请求 - `SEXTORTION` – 检测摄像头威胁、比特币钱包要求、曝光威胁 - `BRAND_DOMAIN_MISMATCH` – 检测内容中的品牌名称与发件人域名不匹配 - `URL signals` – IP 主机、URL 缩短器、punycode、非 HTTPS、可疑 TLD、@ 符号 ### 1.2 机器学习层（次要） 随机森林分类器在标记的邮件数据集上进行训练。它从每封邮件中提取 18 个数值特征，包括： - 紧迫词汇数、敏感词汇数 - 正文长度（对数缩放）、感叹号数量、大写比例 - 基于 URL 的特征：IP 主机、缩短器、HTTPS、子域名数量、TLD 可疑度、punycode - 品牌不匹配信号 机器学习模型使用以下数据集进行训练： - HuggingFace 钓鱼邮件数据集（`zefang-liu/phishing-email-dataset`） - 短信垃圾邮件/正常短信数据集（`dataset_SMS_spam_ham.tsv`） - 合成备用示例（始终激活） ### 1.3 分数融合 最终分数是两层加权的混合： ``` final_score = 0.8 × heuristic_score + 0.2 × ml_score ``` 分类阈值： | 分数范围 | 标签 | |----------|------| | 71 – 00 | 🚨 PHISHING | | 31 – 70 | ⚠️ SUSPICIOUS | | 0 – 30 | ✅ SAFE | ### 1.4 客户端遥测（可选） Gmail 插件可以可选地报告客户端检测到的可疑链接数量。此信号只能 **增加** 怀疑分数，绝不会降低。它上限为 20 个链接，以防止滥用。 ## 2. 如何安装并使用 Gmail 插件 ### 2.1 先决条件 - 已安装 Python 3.11+ - 具有 Gmail 访问权限的 Google 账户 - 用于暴露本地后端的 ngrok（免费账户） - 已克隆的 phish-scan 仓库 ### 2.2 步骤 1 – 设置后端 从项目根目录开始： ``` # Install dependencies .venv-314\Scripts\pip install scikit-learn pandas fastapi uvicorn pydantic python-dotenv httpx # Train the ML model $env:PYTHONPATH = "." python -m detector.detector.ml.train # Start the backend server $env:PHISHSCAN_API_KEY = "my-secret-key" .venv-314\Scripts\python.exe -m uvicorn backend.service.main:app --reload --port 8000 ``` ### 2.3 步骤 2 – 使用 ngrok 暴露后端 ``` ngrok http 8000 ``` 复制显示的 HTTPS URL（例如 `https://abc123.ngrok-free.app`）。 ### 2.4 步骤 3 – 部署 Gmail 插件 1. 打开 [https://script.google.com](https://script.google.com) 并创建一个名为 **“Phish Scan”** 的新项目。 2. 上传仓库中 `addon/` 目录下的所有 `.gs` 文件。 3. 使用正确的 OAuth 范围更新 `appsscript.json`（参见 `addon/appsscript.json`）。 4. 进入 **项目设置 → 脚本属性** 并设置： - `BACKEND_BASE_URL` = `https://abc123.ngrok-free.app` - `BACKEND_API_KEY` = `my-secret-key` 5. 点击 **部署 → 测试部署 → Google Workspace 插件 → 安装**。 6. 打开 Gmail，打开任意邮件，并点击右侧边栏中的 **Phish Scan** 图标。 ### 2.5 使用插件 安装后，插件可在 Gmail 中任意打开的邮件中使用： 1. 在 Gmail 中打开一封邮件 2. 点击右侧边栏中的 **Phish Scan** 图标 3. 点击 **“Scan for Phishing”** 4. 查看结果：标签（PHISHING / SUSPICIOUS / SAFE）、分数（0–100）和详细原因 ## 3. 限制与未来改进 ### 3.1 当前限制 - 机器学习模型在有限数据集上训练，可能无法泛化到所有钓鱼风格 - 后端在本地运行，Gmail 插件需要 ngrok 或云部署才能正常工作 - 不支持 HTML 邮件解析——仅分析纯文本正文 - 模型不分析邮件附件 - ngrok 免费层级会生成新的 URL，需要手动更新脚本属性 - Google Apps Script 插件尚未经过 Google 验证（仅限个人/测试使用） ### 3.2 未来改进 - 在包括 BEC、sextortion 和 callback phishing 示例的更大、更多样化的钓鱼数据集上进行训练 - 添加 HTML 邮件正文解析以提取隐藏 URL 和混淆文本 - 将后端部署到云提供商（例如 Google Cloud Run）以获得永久 URL - 实现反馈循环——允许用户标记误报/漏报以改进模型 - 添加附件扫描支持（PDF、Office 文档） - 扩大品牌冒充检测覆盖更多公司 - 添加对希伯来语等语言的多语言钓鱼检测支持 - 提交 Gmail 插件以通过 Google 验证并移除安全警告

标签：Apex, AV绕过, CEO/CFO冒充, FastAPI, Gmail插件, HTTPS, IP主机, OTP请求, Punycode, SSN请求, TLD可疑度, URGENT语言, URL信号, URL缩短器, 云计算, 企业安全, 信用卡请求, 分类系统, 勒索软件, 反钓鱼, 启发式检测, 品牌域名校验, 商务邮件诈骗BEC, 回调钓鱼, 子域名计数, 安全防护, 密码请求, 敏感信息请求, 未授权收费语言, 机器学习, 比特币钱包, 礼品卡诈骗, 秘密通信请求, 紧急语言, 网络摄像头威胁, 网络资产管理, 规则引擎, 逆向工具, 邮件分析, 邮件安全, 钓鱼检测, 链接检测, 随机森林