DrVerzide/pyguard-scanner

# PyGuard — 恶意软件扫描器 [](https://github.com/DrVerzide/pyguard-scanner/actions/workflows/ci.yml) [](https://www.python.org) [](LICENSE) 一款具有现代桌面 GUI (CustomTkinter) 的**按需恶意软件扫描器**，打包为独立的 Windows `.exe` 程序。它使用与真实检测工具相同的核心技术来扫描文件和文件夹——哈希签名、YARA 规则、词法启发式——此外还支持可选的 VirusTotal 查询。 ## 截图  ## 检测原理（四大引擎） | 引擎 | 功能描述 | 依赖项 | |--------|--------------|-------| | **Signature** | 将每个文件的 SHA-256 与已知的恶意哈希数据库进行比对；此外还包含 EICAR 测试标记。 | — | | **Heuristic** | 标记可疑指标：欺骗性双重扩展名 (`invoice.pdf.exe`)、注入/下载器字符串 (`VirtualAllocEx`, `Invoke-Expression`, `DownloadString`…) 以及高熵（加壳）可执行文件。 | — | | **YARA** | 将文件与内置的 YARA 规则进行匹配——这是签名检测的行业标准。 | `yara-python`（可选） | | **VirusTotal** | 在 70 多种防病毒引擎中查询文件的**哈希**（绝不上传文件本身）。 | 免费 API key + 互联网（可选） | 每个命中项都会提供一个加权分数；PyGuard 将它们汇总以得出最终判定：**clean (安全) / suspicious (可疑) / malicious (恶意)**。 ## 功能特性 - 🖥️ 简洁的 CustomTkinter GUI：选择文件或文件夹，实时查看扫描进度，仅展示检测到的威胁。 - 🧵 扫描在后台线程中运行——窗口绝对不会卡死。 - 🧪 **可通过 EICAR 进行测试**——这是无害的行业标准测试文件，因此您可以证明检测功能是有效的。 - 🚑 **隔离 (Quarantine)**——将标记的文件移动到无法运行的位置（可通过清单文件撤销）。绝不自动删除文件。 - 📄 导出 JSON 格式的报告，用于存档或供 SIEM 使用。 - ⌨️ 同时提供完整的命令行接口。 ## 从源码运行 ``` git clone https://github.com/DrVerzide/pyguard-scanner.git cd pyguard-scanner pip install -e ".[dev]" # includes YARA + pytest # GUI pyguard gui # or: python -m pyguard # CLI pyguard scan "C:\Users\me\Downloads" pyguard scan somefile.exe --json report.json pyguard scan C:\folder --vt-key YOUR_VIRUSTOTAL_KEY # enable VirusTotal ``` ## 构建独立的 `.exe` 程序 ``` # 从项目根目录： powershell -ExecutionPolicy Bypass -File build_exe.ps1 # -> 生成 dist\PyGuard.exe（双击以打开 GUI） ``` 或者直接运行：`pyinstaller pyguard.spec`。 该 `.exe` 文件是一个**构建产物**，且不会提交到 git 中（大小约为 24 MB）。请通过 [GitHub Release](https://docs.github.com/en/repositories/releasing-projects-on-github) 而不是代码仓库进行分发。 ## 验证其实际效果 (EICAR) 确认任何扫描器是否有效的最安全方法是使用 [EICAR 测试文件](https://www.eicar.org/download-anti-malware-testfile/)——这是一个无害的标准字符串，所有防病毒软件都能识别它。 ``` # 创建一个 EICAR-marker 文件（无害）并扫描它： Set-Content flag.txt "EICAR-STANDARD-ANTIVIRUS-TEST-FILE" -NoNewline pyguard scan flag.txt # -> MALICIOUS (EICAR detected) ``` ## 测试 ``` pytest ``` 约 30 个测试用例覆盖了哈希计算、签名数据库、所有启发式规则、扫描器 pipeline（安全 / 可疑 / 恶意 / 超大文件 / 丢失文件）、隔离移动与恢复，以及报告生成。该测试套件是无头模式（无 GUI）的，并在 CI 中支持 Python 3.11–3.13 版本运行。 ## 项目结构 ``` src/pyguard/ ├── engine/ │ ├── hashing.py # streamed MD5/SHA-1/SHA-256 │ ├── signatures.py # known-bad hash DB + EICAR │ ├── heuristics.py # entropy, suspicious strings, double extension │ ├── yara_engine.py # optional YARA │ ├── virustotal.py # optional VT hash lookup │ └── scanner.py # orchestrates all engines, walks directories ├── quarantine.py # reversible quarantine with manifest ├── report.py # console / JSON reports ├── models.py # Detection / FileResult / verdict logic ├── cli.py # command-line interface └── gui.py # CustomTkinter desktop app rules/portfolio.yar # bundled YARA rules data/signatures.json # known-bad hash database (EICAR + placeholder) ``` ## 让检测更贴近实战 此仓库仅包含 EICAR 和占位符，因此它永远不会分发恶意软件。要获得真实的检测覆盖率： - 将来自 **[MalwareBazaar](https://bazaar.abuse.ch/)** (abuse.ch) 的已知恶意哈希添加到 `data/signatures.json` 中。 - 将社区规则（例如 **[YARA-Rules](https://github.com/Yara-Rules/rules)**、Florian Roth 的 *signature-base*）放入 `rules/` 目录中。 - 使用免费的 API key 启用 VirusTotal。 ## 道德声明 PyGuard 是一款**防御性**工具，用于扫描您拥有或被授权检查的文件。它不包含任何恶意软件——仅包含无害的 EICAR 测试标记。检测逻辑透明且有据可查。 ## 许可证 MIT

标签：Ask搜索, Python, VirusTotal, Windows桌面应用, YARA, 云资产可视化, 恶意软件扫描, 无后门, 漏洞挖掘, 逆向工具