NoamHasson1/Malicious-Email-Scorer

# 恶意邮件评分器 ## 概述 这是一款 Gmail 插件，旨在分析已打开的邮件并计算恶意风险评分（0-100），同时提供明确的判定结果和解释。该项目注重简洁的设计、安全意识，并将前端 UI 与繁重的分析后端分离开来。 ## 架构 该系统采用客户端-服务端架构构建，遵循关注点分离 原则和纵深防御 策略： * **前端（客户端）：** 使用 Google Apps Script（基于卡片的插件框架）开发。它负责提取邮件元数据（发件人、主题、正文、链接和附件名称），并充当轻量级客户端。 * **后端（服务端）：** 使用 Python 和 FastAPI 构建的高性能 REST API。 * **纵深防御流水线：** 服务端实现了双路径路由系统： * **快速路径：** 确定性的 O(1) 规则（例如，黑名单、URL 解析、附件扩展名）以及外部 API 轮询，用于立即捕获已知威胁。 * **慢速路径：** 回退到 LLM 语义分析，以应对复杂的、零日漏洞 或基于上下文的威胁。 * **Prompt 层：** LLM 的系统指令与业务逻辑解耦，并存储在专门的文本文件（`prompts/system_prompt.txt`）中，以防范 Prompt 注入攻击，并允许轻松更新规则。 * **隧道穿透：** 在开发过程中使用 `ngrok` 将本地 FastAPI 服务端暴露给 Google 的云环境。 ## 使用的 API 1. **Google Workspace Add-ons API (CardService & GmailApp)：** 用于构建 UI 并提取邮件上下文数据。 2. **VirusTotal API (v3)：** 用于外部威胁情报，在到达 LLM 之前根据全球安全厂商扫描提取的 URL。 3. **OpenAI API (gpt-4o-mini)：** 用作核心智能引擎，分析文本中的网络钓鱼指标、紧急性和域名欺骗，并通过 Pydantic 模型返回结构化的 JSON 响应。 ## 已实现的功能 * **自动化提取：** 无缝提取发件人详细信息、主题、正文、内嵌 URL 以及附件元数据（名称和扩展名）。 * **多层安全（快速路径）：** 自动标记恶意附件（例如 `.pdf.exe` 等双重扩展名）、可疑的 TLD 和 URL 缩短服务（通过 `urllib` 安全解析）。 * **威胁情报集成：** 主动查询 VirusTotal 以获取 URL 信誉评分，有效阻止已知威胁，从而避免产生 LLM token 成本。 * **AI 驱动的代理分析：** 利用配置了严格网络安全防护措施的 LLM，来理解绕过确定性过滤器的邮件的上下文和语气。 * **内存缓存：** 对传入的邮件 payload 进行哈希处理（MD5），为以前扫描过的邮件提供缓存分析，从而显著降低 API 延迟和成本。 * **健壮的测试套件：** 包含自动化的 `pytest` 套件，通过 API 模拟测试边缘情况、快速路径确定性逻辑和 LLM 行为。 * **结构化的 UI 与优雅的错误处理：** 显示简洁、原生的 Gmail 界面。捕获 API 超时或 HTTP 错误，并在 Gmail UI 中整齐地显示它们。 ## 已知的限制与权衡 * **本地隧道穿透 (ngrok)：** 当前的部署依赖于通过 `ngrok` 路由到本地计算机。在生产环境中，FastAPI 后端应部署到云服务提供商（例如 AWS ECS / GCP Cloud Run），并配置适当的身份验证。 * **易失性缓存：** 当前的缓存机制是内存级的（Python 字典）。在可扩展的多实例生产环境中，应将其替换为像 Redis 这样的分布式缓存。 * **Payload 截断：** 为了防止 token 限制耗尽和 API 滥用，邮件正文在发送到后端之前被硬截断为 5000 个字符。 * **VirusTotal 速率限制：** 当前实现使用的是 VirusTotal API 的免费层。在高吞吐量的生产环境中，将需要商业 API 许可证，以防止出现 `429 Too Many Requests` 错误。

标签：AV绕过, DLL 劫持, FastAPI, Gmail插件, Petitpotam, 大语言模型, 威胁情报, 安全规则引擎, 开发者工具, 逆向工具, 邮件安全, 钓鱼检测