stickkersz/usb-virus-scanner

# USB 病毒扫描器 企业级恶意软件扫描器，适用于 **Windows 上的 USB 驱动器和硬盘**。 插入瞬间自动扫描任何可移动驱动器，将受感染 的文件移出驱动器进行隔离，并为 IT 部门写入审计日志和报告。 ## 检测层 | 层级 | 捕获内容 | 引擎 | |-------|-----------------|--------| | **ClamAV 签名** | 数以百万计的已知病毒/恶意软件，包括压缩包内的 | `clamscan` / `clamdscan` | | **公司哈希黑名单** | 来自您自己 IR / 威胁情报的已知不良文件 | SHA-256 匹配 | | **YARA 规则** | 行为模式，ClamAV 遗漏的零日漏洞 | `yara-python` | | **USB 启发式** | `autorun.inf` 自启动，双扩展名 (`invoice.pdf.exe`)，高风险脚本投放器 | 内置 | 确认感染后，文件将被移动到加密中和的 隔离区（经过 XOR 混淆，因此无法通过双击执行）， 记录日志，并包含在每次扫描的报告中。一切都可通过 `quarantine --restore` 撤销。 ## 工作原理 两个前端（`gui.py`、`cli.py`）驱动一个共享的 **`ScanEngine`**。扫描 作为 pipeline 运行： ``` insert USB / pick target │ ┌────────▼─────────┐ │ 1. Walk the tree │ os.scandir, once. Collect path+size+mtime. │ (single pass) │ Apply max-file-size cap. └────────┬─────────┘ ┌────────▼─────────┐ │ 2. Cache filter │ Drop files unchanged since last CLEAN scan │ │ (path+size+mtime match) → candidate list. └────────┬─────────┘ ┌────────▼─────────┐ │ 3. ClamAV │ Candidates handed to clamscan/clamdscan via │ signatures │ --file-list (+ --multiscan). Parses "FOUND". └────────┬─────────┘ ┌────────▼─────────┐ │ 4. Heuristic │ Thread pool. Per file: autorun.inf, double │ layer │ extension, SHA-256 hash blocklist, YARA rules. │ │ Deep read gated to risky/small files (fast mode). └────────┬─────────┘ ┌────────▼─────────┐ │ 5. Quarantine │ INFECTED files moved off the drive, XOR- │ │ neutralized, indexed for restore. └────────┬─────────┘ ┌────────▼─────────┐ │ 6. Log + report │ Rotating log, JSONL for SIEM, text report. │ + cache clean │ Clean files recorded so next scan skips them. └──────────────────┘ ``` **分层检测是有意设计的：** ClamAV 捕获数以百万计的已知 签名；哈希黑名单捕获您自己事件响应团队 标记的文件；YARA 捕获 ClamAV 尚无 签名的行为模式和零日漏洞；启发式算法捕获 USB 特有的传播技巧（自启动、 伪装），这些技巧根本不是“恶意软件字节”。任何 层级都可以独立标记文件。 **可移动驱动器检测**通过 `ctypes` 使用 Win32 API（`GetLogicalDrives` / `GetDriveType`）——无需服务，无需管理员权限，支持 Windows 7→11。 `watch` 命令轮询驱动器的插入并在插入时自动扫描。 ### 项目结构 ``` usb-virus-scanner/ ├── cli.py # CLI entry point (scan/watch/drives/quarantine/update) ├── gui.py # Tkinter desktop GUI ├── config.yaml # all tunables (paths, speed, detection knobs) ├── scanner/ │ ├── engine.py # ScanEngine + ClamAV wrapper (the pipeline above) │ ├── heuristics.py # autorun/double-ext + hash blocklist + YARA │ ├── quarantine.py # move / neutralize / restore + index │ ├── cache.py # skip unchanged-clean files │ ├── watcher.py # USB insert detection (Win32 ctypes) │ ├── reporter.py # logging + JSONL + text reports │ ├── paths.py # source vs frozen-exe base dir │ ├── config.py # config load + defaults │ └── models.py # Detection / ScanResult types ├── signatures/ │ ├── hash_blocklist.txt # your SHA-256 blocklist │ └── yara/usb_threats.yar # starter YARA rules ├── tests/make_eicar.py # writes the harmless EICAR AV test file └── build/ # PyInstaller spec + Inno Setup + icon → setup.exe ``` ## 从源码运行（开发 / 快速试用） 适用于 Windows、macOS 和 Linux（在非 Windows 系统上，驱动器检测回退到挂载点， 因此您可以在任何地方进行开发）。 ``` git clone https://github.com/stickkersz/usb-virus-scanner.git cd usb-virus-scanner python -m pip install -r requirements.txt python cli.py drives # list removable drives python cli.py scan # scan a folder/drive python gui.py # launch the GUI ``` 快速试用时 ClamAV 是可选的——没有它，启发式 + 哈希 + YARA 层仍然会运行（您会看到“未找到 ClamAV”的提示）。安装 ClamAV 以获得 完整的签名覆盖。 ## 安装 (Windows) 提升权限的 PowerShell： ``` powershell -ExecutionPolicy Bypass -File install.ps1 # 添加 -RegisterWatcher 以在登录时自动启动 insert-watcher： powershell -ExecutionPolicy Bypass -File install.ps1 -RegisterWatcher ``` 安装 ClamAV（通过 winget）、Python 依赖项，更新签名，创建 `C:\ProgramData\USBVirusScanner\{Quarantine,Logs,Reports}`。 ## GUI（最终用户） ``` python gui.py ``` 简单的窗口：选择一个驱动器（或**浏览…**一个文件夹），点击**扫描**，观察 进度，查看带有颜色标记的威胁列表以及 CLEAN/THREATS（干净/有威胁）横幅。受感染的 文件会被自动隔离；**隔离区…** 打开一个列表，在其中可以 恢复文件。勾选**仅报告** 可在不移动任何文件的情况下进行检测。 基于 Tkinter 构建——随 Python 附带，因此前端 无需额外安装任何内容。扫描在后台线程中运行；窗口保持响应。 为非技术人员制作一个指向 `pythonw gui.py` 的桌面快捷方式（注意 `pythonw` = 无控制台 窗口）。 ## CLI（IT / 企业设备集群） ``` python cli.py drives # list attached removable drives python cli.py scan E:\ # scan a drive now (quarantines threats) python cli.py scan E:\ --no-quarantine # report only, touch nothing python cli.py watch # auto-scan every USB as it is inserted python cli.py update # refresh ClamAV signatures (freshclam) python cli.py quarantine # list quarantined files python cli.py quarantine --restore --to D:\recovered.bin ``` 退出代码 `0` = 干净，`1` = 发现威胁——可在脚本 / GPO 中使用。 ## 构建员工安装程序（单个 .exe） 在装有 Python 3.9+ **且** [Inno Setup 6](https://jrsoftware.org/isdl.php) 的 Windows 构建机器上： ``` powershell -ExecutionPolicy Bypass -File build\build.ps1 ``` 生成 **`Output\USBVirusScannerSetup.exe`** —— 一个可以交付给 员工的单个文件。它会： - 使用 PyInstaller 将 `gui.py` + `cli.py` 冻结为 `USBVirusScanner.exe` (GUI) 和 `usbscan.exe` (CLI) —— **员工 PC 上无需 Python**； - 使用 Inno Setup 将它们封装为一个安装可执行文件。 员工运行 `USBVirusScannerSetup.exe` 时会看到： - 安装到 `C:\Program Files\USBVirusScanner`，开始菜单 + 可选桌面快捷方式； - 复选框 **“插入时自动扫描每个 USB”** → 注册一个 SYSTEM 计划任务； - 复选框 **“安装/刷新 ClamAV”** → 通过 winget 拉取 ClamAV + 更新签名； - 创建 `ProgramData\USBVirusScanner\{Quarantine,Logs,Reports}` 文件夹。 双击 → 下一步 → 完成。静默/GPO 安装：`USBVirusScannerSetup.exe /VERYSILENT /NORESTART`。 ### 完全离线安装程序（员工 PC 上零下载） 默认情况下，安装程序会在安装过程中从 互联网（winget + freshclam）获取 ClamAV 引擎 + 病毒数据库。要将**所有内容**打包到 一个安装文件中，以便员工**完全不需要互联网**： ``` # 在有 internet 的构建机器上，执行一次： powershell -ExecutionPolicy Bypass -File build\fetch-vendor.ps1 # downloads ClamAV + signatures into vendor\ powershell -ExecutionPolicy Bypass -File build\build.ps1 # bundles them # 或者一次性完成这两项操作： powershell -ExecutionPolicy Bypass -File build\build.ps1 -Offline ``` 构建在编译时会自动检测 `vendor\ClamAV\`：如果存在，ClamAV 和完整的签名数据库将被打包到 `USBVirusScannerSetup.exe` 中，并且 所有在线步骤都将被移除。员工只需双击——引擎、数据库、 扫描器、GUI、快捷方式、自动扫描任务，全部从那个文件 离线安装。当您想要刷新捆绑的 签名时，请重新运行 `fetch-vendor.ps1`。（`vendor\` 被 git 忽略——大约 450 MB 的 Windows 二进制文件，未 提交。） 应用程序图标（`build\app.ico`，一个安全盾牌 + USB 标记）被嵌入到 两个 exe 中并供快捷方式使用。使用 `python build\make_icon.py`（需要 Pillow）重新生成/编辑它。 构建产物（`dist\`、`Output\`）被 git 忽略。 ## 企业集群部署 - **推荐：** 通过 SCCM/Intune/GPO 推送 `USBVirusScannerSetup.exe` 并静默安装：`USBVirusScannerSetup.exe /VERYSILENT /NORESTART`。 （源码安装替代方案：推送文件夹并运行 `install.ps1 -RegisterWatcher`。） - 监视器作为 SYSTEM 下的启动计划任务运行；自动扫描每个插入的 USB，无需用户操作。 - 将 `logging.jsonl` 指向共享路径，或将 `events.jsonl` 发送到您的 SIEM 以实现全公司可见性。 - 集中维护 `signatures/hash_blocklist.txt` 并将其同步出去；在发生 安全事件时添加哈希值。 ## 测试其功能 ``` python tests\make_eicar.py C:\temp\eicartest # writes harmless EICAR test file python cli.py scan C:\temp\eicartest # must report a detection ``` EICAR 是业界标准的无害 AV 测试字符串——每个扫描器都会标记 它，但它没有任何实际作用。 ## 在慢速笔记本电脑上的速度 经过优化，使老旧/缓慢的公司机器也能快速扫描： - **单次目录树遍历** —— 驱动器仅枚举一次；ClamAV 获取一个文件列表， 而不是重新遍历目录树本身（过去是双倍磁盘 IO）。 - **扫描缓存**（`use_cache`）—— 自上次干净扫描以来未更改的文件将被 完全跳过（路径 + 大小 + mtime）。重新扫描相同的 USB / 公司 硬盘几乎是瞬间完成的。缓存位于 `…\Logs\scan_cache.json`。 - **快速模式**（`deep_scan_all: false`）—— SHA-256 + YARA 仅在高风险类型 文件或小于 `deep_scan_max_mb`（默认为 50）的文件上运行。大型电影/备份不会 进行逐字节读取。设置 `deep_scan_all: true` 可获得最高彻底性。 - **并行** —— `workers: auto` 根据 CPU 核心数扩展线程（已设上限，防止单磁盘笔记本电脑发生严重抖动）；`multiscan: true` 使用 clamd 的并行 引擎。 - **跳过压缩包** 以在弱硬件上获得额外速度：设置 `scan_archives: false`。 非常慢的笔记本电脑的调优备忘单：`deep_scan_max_mb: 20`， `scan_archives: false`，保持 `use_cache: true`。对于隔离网络的高安全性 机器：`deep_scan_all: true`，`scan_archives: true`。 ## 配置 所有路径和行为都存在于 `config.yaml` 中（ClamAV 路径、隔离目录、 可疑扩展名、worker、轮询间隔等）。内置默认值， 因此即使文件丢失，工具也能运行。 ## Windows 兼容性 驱动器检测通过 `ctypes` 使用 Win32 API（`GetLogicalDrives` / `GetDriveType`）—— 适用于 Windows 7 → 11 / Server，无需额外服务。ClamAV 和 Python 3.9+ 是唯一的先决条件。在 Linux/macOS 上，它回退到 挂载点轮询，因此您可以在非 Windows 环境下进行开发和测试。 ## 注意事项 / 限制 - 隔离“中和”是 XOR 混淆，旨在防止意外执行——它 不是对样本的加密保护。 - 保持 ClamAV 签名最新（`update` / 定时 `freshclam`）——检测 效果仅取决于数据库的质量。 - 提升权限运行监视器，以便它可以读取/隔离其他用户拥有的文件。

标签：ClamAV, Web 安全测试, YARA, 云资产可视化, 搜索语句（dork）, 漏洞挖掘, 系统运维, 终端安全, 自动扫描, 逆向工具, 防恶意软件