Yessineee/NullThreat

# NullThreat     ## 截图 | 弹出窗口 | 概览 | |-------|----------| |  |  | | 扫描历史 | 威胁详情 | |-------------|---------------| |  |  | | 设置 | |----------| |  | ## 功能 - **自动 PDF 检测** — 监听浏览器下载事件，并在 PDF 文件下载完成的瞬间进行扫描，无需任何手动干预 - **实时威胁评分** — 基于所有 VirusTotal 引擎的检测率，计算 0–100 的综合威胁评分 - **完整的引擎分析** — 查看 90 多个防病毒引擎的单独判定结果，按严重程度排序（恶意 → 可疑 → 干净） - **扫描历史** — 将所有过去的扫描记录保存在持久的本地存储中，支持按状态搜索和过滤 - **导出** — 以 CSV 或 JSON 格式下载完整的扫描历史 - **智能通知** — 在扫描开始和完成时发送桌面通知，可配置为仅在检测到威胁时通知 - **暗色/亮色主题** — 跨会话持久化保存，并在弹出窗口和控制台之间同步 - **可折叠控制台** — 带有侧边栏导航的全标签页 React 控制台，可折叠为仅图标模式 - **API 密钥管理** — 将 VirusTotal API 密钥安全地存储在 `chrome.storage.sync` 中，支持掩码显示和连接测试 - **Rate limiting** — 内置请求队列，遵守 VirusTotal 免费版限制（4 次请求/分钟） ## 架构 NullThreat 遵循三层扩展架构： ``` ┌─────────────────────────────────────────────────────┐ │ Browser Layer │ │ Downloads API · Storage · Tabs API │ └──────────────────────┬──────────────────────────────┘ │ ┌──────────────────────▼──────────────────────────────┐ │ Extension Core │ │ │ │ ┌─────────────┐ ┌──────────┐ ┌───────────────┐ │ │ │ Service │ │ Popup UI │ │ Dashboard │ │ │ │ Worker │◄─►(React) │ │ (React SPA) │ │ │ │ │ │ │ │ │ │ │ │ · Download │ │ · Stats │ │ · Overview │ │ │ │ listener │ │ · Status │ │ · History │ │ │ │ · Scan queue│ │ · Toggle │ │ · Threat │ │ │ │ · Messages │ │ │ │ Detail │ │ │ └──────┬──────┘ └──────────┘ │ · Settings │ │ │ │ └───────────────┘ │ │ ┌──────▼──────┐ ┌──────────┐ │ │ │ VT Client │ │ Storage │ │ │ │ + Queue │ │ Manager │ │ │ └─────────────┘ └──────────┘ │ └──────────────────────┬──────────────────────────────┘ │ ┌──────────────────────▼──────────────────────────────┐ │ External Services │ │ VirusTotal API v3 │ │ /urls · /analyses · /files │ └─────────────────────────────────────────────────────┘ ``` **关键架构决策：** - **Manifest v3 service worker** — 临时后台脚本，使用 `Map` 缓存来关联 `onCreated` 和 `onChanged` 下载事件，避免了不可靠的 `chrome.downloads.search` 回调模式 - **基于 URL 的扫描** — 直接将下载 URL 提交给 VirusTotal，而不是重新获取文件，从而绕过扩展来源固有的 CORS 限制 - **无状态弹出窗口** — 弹出窗口每次打开时都会从 `chrome.storage` 读取数据，并监听来自 service worker 的 runtime 消息以获取实时扫描状态 - **无 React Router** — 控制台使用轻量级的 `useState` 路由，因为弹出窗口和控制台是独立的 HTML 入口点，而不是单个 SPA - **独立的入口点** — 弹出窗口和控制台都有各自的 `main.jsx` 和 HTML 文件，由 CRXJS 独立打包 ## 技术栈 | 层级 | 技术 | |-------|-----------| | 扩展打包器 | [CRXJS](https://crxjs.dev/vite-plugin) + Vite | | UI 框架 | React 18 | | 样式 | Tailwind CSS v3 + CSS 变量 | | 组件库 | shadcn/ui (Radix UI primitives) | | 图标 | Lucide React | | 字体 | Inter + JetBrains Mono | | 存储 | `chrome.storage.local` + `chrome.storage.sync` | | 威胁情报 | [VirusTotal API v3](https://developers.virustotal.com/reference/overview) | ## 安装说明 ### 前置条件 - Node.js 18 或更高版本 - 基于 Chromium 的浏览器（Chrome、Brave、Edge） - 一个免费的 [VirusTotal API 密钥](https://www.virustotal.com/gui/join-us) ### 设置 ``` # Clone the repository git clone https://github.com/Yessineee/NullThreat.git cd NullThreat # Install dependencies npm install # Add your VirusTotal API key echo "VITE_VT_API_KEY=your_api_key_here" > .env # Build the extension npm run build ``` ### 在浏览器中加载 1. 打开 `chrome://extensions`（或 `brave://extensions`） 2. 启用 **开发者模式**（右上角切换开关） 3. 点击 **加载已解压的扩展程序** 4. 选择 `dist/` 文件夹 ### 首次运行 1. 点击浏览器工具栏中的 NullThreat 图标 2. 在设置界面输入您的 VirusTotal API 密钥 3. 点击 **保存 API 密钥** 4. 下载任何 PDF — NullThreat 将自动对其进行扫描 ## 工作原理 ### 扫描流程 ``` PDF download starts │ ▼ chrome.downloads.onCreated → cache item in Map │ ▼ chrome.downloads.onChanged (state: complete) │ ▼ Retrieve item from cache → verify PDF by MIME type │ ▼ Submit URL to VirusTotal /urls endpoint │ ▼ Poll /analyses/{id} every 8s (up to 20 attempts) │ ▼ Calculate threat score: Math.round((malicious / total) * 100) │ ├── score = 0 → status: clean ✓ ├── score > 0 → status: threat ✗ └── no data → status: unknown ? │ ▼ Save to chrome.storage.local Send runtime message to popup/dashboard Show desktop notification ``` ### 威胁评分 威胁评分是一个 0–100 的整数，表示将文件标记为恶意的 VirusTotal 引擎的百分比： ``` threatScore = Math.round((maliciousEngines / totalEngines) * 100) ``` | 评分 | 状态 | 含义 | |-------|--------|---------| | 0 | 干净 ✓ | 没有引擎检测到威胁 | | 1–24 | 低威胁 | 少数引擎将其标记为恶意 | | 25–49 | 中等威胁 | 显著的检测率 | | 50–100 | 高威胁 | 大多数引擎将其标记为恶意 | | — | 未知 | 文件不在 VirusTotal 数据库中 | ## 已知限制 - **仅限 URL 扫描** — NullThreat 扫描的是下载 URL 而不是文件二进制数据。从经过身份验证或私有 URL（大学门户、企业内联网）下载的文件可能无法被 VirusTotal 扫描。 - **VirusTotal 免费版** — 限制为 4 次请求/分钟和 500 次请求/天。大量使用会耗尽每日配额。 - **扫描延迟** — VirusTotal 上的 URL 分析需要 30–90 秒。扩展程序将在此期间轮询结果。 - **仅限 PDF** — 目前仅限于通过 MIME 类型（`application/pdf`）或 URL 扩展名识别的 PDF 文件。 - **无法上传文件** — 由于扩展来源的 CORS 限制，无法将未知文件（不在 VT 的数据库中）上传进行全新扫描。 ## 路线图 - [ ] **后端代理** — 轻量级 Node.js 服务器，用于处理将文件上传至 VirusTotal 和 MetaDefender 的操作，绕过浏览器的 CORS 限制 - [ ] **集成 MetaDefender** — 使用 OPSWAT MetaDefender（免费版 5000 次请求/天）进行双引擎扫描，以获取综合威胁评分 - [ ] **Firefox 支持** — 使用 `webextension-polyfill` 进行跨浏览器构建 - [ ] **扩展文件类型** — 除了 PDF 外，还扫描 `.exe`、`.zip`、`.docx` 下载文件 - [ ] **拖放扫描** — 直接从控制台手动触发扫描，无需下载 - [ ] **威胁历史图表** — 每周/每月扫描活动可视化 ## 许可证 MIT © [Yessineee](https://github.com/Yessineee)

标签：Ask搜索, Manifest V3, React, Syscalls, VirusTotal, 威胁情报, 开发者工具, 搜索语句（dork）, 文件扫描, 浏览器扩展, 自定义脚本