Kartik0219/malscan

GitHub: Kartik0219/malscan

一款完全离线运行的本地恶意软件按需扫描器，结合哈希、熵值、PE分析、YARA 等多引擎检测技术，为每个文件输出统一判定结果。

Stars: 0 | Forks: 0

# malscan 一个本地、按需运行的恶意软件扫描器。它将五种检测技术结合，为每个文件生成单一判定结果 —— 完全离线运行，无云 API，无遥测。 **在线演示：** —— 一个安全的、仅限上传的公开版本（完整的本地仪表板仅支持 CLI）。 ## 快速开始 —— 下载与运行（分步指南）有两种方式可以开始。**选项 A** 最快（无需 Python）；**选项 B** 从源码运行，且不会产生任何操作系统警告。 ### 选项 A —— 下载应用（无需 Python） 1. 打开 [**Releases 页面**](https://github.com/Kartik0219/malscan/releases/latest)。 2. 在 **Assets** 下，下载适用于您系统的文件： - **Windows:** `malscan-windows-x64.exe` - **macOS (Apple Silicon):** `malscan-macos-arm64` 3. 运行它： - **Windows:** 双击 `.exe` 文件。首次运行时，Windows SmartScreen 可能会提示 *"Windows protected your PC"* -> 点击 **More info -> Run anyway**（该程序未签名，但未感染病毒 —— 详见[下文说明](#running-it-safely-no-smartscreen--gatekeeper-warnings））。 - **macOS:** 在“下载”文件夹中打开 Terminal 并运行 `chmod +x malscan-macos-arm64 && ./malscan-macos-arm64`。如果被 Gatekeeper 拦截， **右键点击该文件 -> Open** 一次以允许运行。 4. 扫描仪表盘将在浏览器中打开，地址为 ****。您也可以在终端中将其作为命令行工具使用： # Windows malscan-windows-x64.exe scan "C:\Users\you\Downloads" # macOS ./malscan-macos-arm64 scan ~/Downloads ### 选项 B —— 从源码运行（无警告；需要 Python 3） 1. 安装 **[Python 3](https://www.python.org/downloads/)**（在 Windows 上请勾选 *"Add Python to PATH"*）。 2. 获取代码 —— 使用 git，或下载 ZIP 压缩包： git clone https://github.com/Kartik0219/malscan.git cd malscan *(没有 git？在仓库页面点击 **Code -> Download ZIP**，然后解压即可。)* 3. 启动它： - **Windows:** 双击 **`run_malscan.bat`**（它会自动安装所需依赖并打开仪表盘）。 - **macOS / Linux:** chmod +x run_malscan.sh ./run_malscan.sh 4. 在浏览器中打开 ****。 ### 首次扫描（命令行） ``` # 扫描单个文件 python -m malscan scan suspicious.exe # 扫描整个 Downloads 文件夹，仅显示 suspicious-or-worse python -m malscan scan ~/Downloads --min-severity suspicious ``` 它会为每个文件输出一个判定结果（`clean` / `info` / `suspicious` / `malicious`），并且如果发现任何恶意文件，将以退出代码 `1` 退出。就是这么简单 —— 阅读本 README 的其余部分以了解报告、隔离区、实时监控及其他引擎。 ## 安全运行（无 SmartScreen / Gatekeeper 警告） malscan 是纯 Python 编写的，因此最安全且无警告的运行方式是**从源码** 运行 —— 操作系统没有未签名的 `.exe` 或二进制文件需要标记。 **Windows** —— 双击 **`run_malscan.bat`**（或在终端中运行它）。它会安装依赖项并在打开仪表盘。 **macOS / Linux**: ``` chmod +x run_malscan.sh ./run_malscan.sh # http://127.0.0.1:8080 ``` 或在任何平台上手动运行： ``` pip install -r requirements.txt flask waitress python serve.py # http://127.0.0.1:8080 ``` ## 检测引擎 | 引擎 | 技术 | 可引发的判定结果 | |--------|-----------|----------------------| | **hash** | 基于 SHA-256 / MD5 与黑名单匹配 | `malicious` | | **heuristic** | 加权静态特征：整体文件及 PE 节的熵 + 高风险导入 | `suspicious` | | **filetype** | Magic bytes 与声明的扩展名不匹配 + 双扩展名欺骗 | `suspicious` | | **logical** | 多条件签名（ClamAV `.ldb` 风格的布尔规则） | 取决于具体规则 | | **yara** | YARA 规则匹配 (`yara-python`) | 取决于具体规则 (`suspicious`/`malicious`) | | **ml** *(可选)* | 基于字节/PE 特征训练的逻辑回归模型 | `suspicious` | | **reputation** *(可选)* | 本地流行度缓存 —— 标记前所未见的可执行文件 | `info` | | **virustotal** | 可选的哈希查询，对比 VirusTotal 的 AV 共识结果 | 取决于共识 | hash 和 heuristic 引擎完全使用标准库。`pefile` 和 `yara-python` 是可选的 —— 如果未安装，这些检查会优雅降级，并且扫描的其余部分仍会继续运行。文件还会在**压缩包内部**被遍历（见下文）。 ### 启发式评分启发式引擎将*加权特征*汇总为 `[0, 1]` 范围内的风险评分，并且仅在分数超过阈值时才标记为 `suspicious` —— 单个高风险导入不会直接判定文件违规，但多个特征组合（或打包的 PE 节）则会。压缩和媒体格式（zip、gzip、png、jpeg 等）**豁免**于整体文件熵检查，因为它们在设计上本身就是高熵的；它们的内部内容会由压缩包遍历器进行检查。 ## 压缩包扫描 `.zip`、`.tar`（包括 `.tar.gz`/`.tar.xz`）以及纯 `.gz` 流中的文件也会被扫描 —— 直接**在内存中**遍历，绝不解压到磁盘上。这意味着 zip-slip 类的漏洞无法发生（一个名为 `../../etc/passwd` 的成员只是一个无效的标签），并且解压炸弹受到显式预算的限制（针对每个成员、总字节数、成员数量和嵌套深度）。成员路径通过 `!` 组合，例如 `bundle.zip!evil.exe`。使用 `--no-archives` 可禁用此功能。 ## 下载 (Windows & macOS) 预编译的二进制文件位于 [**Releases**](https://github.com/Kartik0219/malscan/releases) 页面 —— 无需 Python： | 平台 | 文件 | |----------|------| | Windows 10/11 (x64) | `malscan-windows-x64.exe` | | macOS (Apple Silicon) | `malscan-macos-arm64` | | macOS (Intel) | `malscan-macos-x64` | - **双击**即可在浏览器中打开仪表盘，**或者**在终端中作为 CLI 运行：`malscan-windows-x64.exe scan `。 - 这些二进制文件是**未签名**的，因此操作系统会显示一次性警告： - **Windows:** SmartScreen -> *More info* -> *Run anyway*。 - **macOS:** 右键点击 -> *Open* (或运行 `xattr -d com.apple.quarantine ./malscan-macos-arm64 && chmod +x ./malscan-macos-arm64`)。 - 某些杀毒软件引擎可能会标记 PyInstaller 生成的二进制文件（对于扫描器来说这很讽刺） —— 这是误报；通过以下方法从源码安装即可避免。 ## 安装 ``` pip install -r requirements.txt # optional extras: pefile, yara-python ``` 核心扫描器零依赖运行；扩展项可解锁 PE 和 YARA 功能。 ## 用法 ``` # 扫描单个文件 python -m malscan scan suspicious.exe # 扫描目录（默认递归），写入 JSON + HTML 报告 python -m malscan scan ./downloads --json report.json --html report.html # 仅显示 suspicious-or-worse，非递归 python -m malscan scan ./downloads --no-recursive --min-severity suspicious ``` HTML 报告是一个独立的单文件（无外部资源），您可以在任何浏览器中打开或分享 —— 非常适合将扫描结果附加到工单中。如果发现任何 `malicious` 内容，退出代码为 `1`，否则为 `0` —— 非常适合用于 CI 流水线和 pre-commit 钩子。 ### SARIF 输出 (GitHub 代码扫描) 生成 [SARIF 2.1.0](https://sarifweb.azurewebsites.net/) 报告，以便检测结果能作为警报显示在仓库的 **Security** 标签页中，与 CodeQL 并列： ``` python -m malscan scan ./artifacts --sarif malscan.sarif ``` 每个发现都会成为一个 SARIF `result`（严重程度映射为 `error`/`warning`/`note`，并带有 GitHub `security-severity` 分级）；MITRE ATT&CK ID 包含在 result 属性中。从 workflow 上传它： ``` - run: python -m malscan scan ./artifacts --sarif malscan.sarif - uses: github/codeql-action/upload-sarif@v3 with: sarif_file: malscan.sarif ``` ## 判定结果每个文件获得一个判定结果 —— 即所有引擎发现中严重程度最高的结果： `clean` < `info` < `suspicious` < `malicious` ## 检测原理 - **Hashes** 能立即捕获*已知的*恶意文件。内置的黑名单预置了 [EICAR 测试文件](https://www.eicar.org/) 的 SHA-256 哈希（一个无害的行业测试字符串，并非真正的恶意软件），以便您验证扫描器是否正常工作。 - **Entropy** 标记字节分布接近随机（≥ 7.5 bits/byte）的文件，这是加壳或加密的典型特征。这只是*信号，而非* *证据* —— 合法的安装程序也会加壳，因此它只作为权重参考，绝不单独作为定罪依据，并且压缩/媒体格式豁免于此。 - **PE analysis** 解析 Windows 可执行文件，查找高熵（加壳）的节以及常被滥用于进程注入和反调试的导入（`WriteProcessMemory`、`CreateRemoteThread`、`IsDebuggerPresent` 等）。 - **File-type masquerading** 将文件真实的 magic bytes 与其名称所声明的类型进行比对 —— 例如实际上是 PE/ELF/Mach-O 可执行文件的 `.pdf` 或 `.jpg`，或者像 `invoice.pdf.exe` 这样的双扩展名。映射到 MITRE `T1036.008` / `T1036.007`。纯标准库实现；设计上几乎零误报。 - **YARA** 运行来自 `signatures/yara/` 的模式规则。放入精选的规则源（例如 [signature-base](https://github.com/Neo23x0/signature-base)）以扩大覆盖范围。 ## 扩展功能 - **更多哈希：** 将 ` ` 行追加到 `signatures/hash_blocklist.txt` 中。 - **更多规则：** 将 `.yar` 文件放入 `signatures/yara/`。规则的 `meta` 可以设置 `severity = "suspicious"`，以从默认的 `malicious` 降级。 - **逻辑签名：** 在 `signatures/logical/` 下添加 `.msig` 规则（见下文）。 ### 逻辑签名单个哈希或单一字符串过于生硬；真正的引擎会将多个子模式与布尔逻辑结合起来。`logical` 引擎为 malscan 带来了 ClamAV-`.ldb` 风格的多条件规则。`signatures/logical/*.msig` 文件的每一行内容如下： ``` name ; severity ; techniques ; expression ; sub0 ; sub1 ; ... ``` `expression` 是基于子签名索引的布尔逻辑（`&`, `|`, 括号）；每个 `subN` 是 `str:LITERAL` 或十六进制模式（`4d5a`, `??` = 任意字节, `*` = 间隔）。例如，一个精确的进程注入规则 —— 单独存在任何一个导入是无害的，但同时存在三者则不然： ``` PE_Injection_Trio ; suspicious ; T1055 ; 0 & 1 & 2 & 3 ; 4d5a ; str:VirtualAllocEx ; str:WriteProcessMemory ; str:CreateRemoteThread ``` 布尔表达式由一个小型递归下降评估器解析（绝不使用 `eval`），因此格式错误或恶意的规则文件会被跳过，而不会被执行。 ## 测试 ``` python -m pytest ``` 测试在内存中使用 EICAR 字符串进行哈希检测。磁盘扫描器测试特意使用了合成的黑名单 payload，而不是将真正的 EICAR 写入磁盘 —— 因为在 Windows 上，主机杀毒软件会在测试回读之前就将 EICAR 隔离。 ## 隔离区将标记的文件隔离到本地保险库中。存储的 blob 经过 XOR 混淆，因此它们无法被执行，也不会重新触发访问时扫描的 AV；恢复过程是逐字节无损的。每个条目都保留一个 JSON 附属文件（包含原始路径、哈希、判定结果、时间）。 ``` # 扫描并自动隔离任何恶意文件 python -m malscan scan ./downloads --quarantine # 管理 vault python -m malscan quarantine list python -m malscan quarantine restore [--to ] python -m malscan quarantine delete ``` ## 实时监控监视一个或多个文件夹，并在文件**创建或修改时**进行扫描 —— 这是与一次性 `scan` 命令对应的访问时扫描工具，非常适合用于 Downloads 文件夹或上传目录： ``` # 监视文件夹；报告 suspicious-or-worse，自动隔离任何恶意文件 python -m malscan monitor ~/Downloads --quarantine # 监视多个路径，同时使用 ML 模型进行评分，每秒轮询两次 python -m malscan monitor ./incoming ./uploads --ml-model ml_model.json --interval 0.5 ``` 已更改的文件只有在**稳定下来**后才会被扫描（即在两次轮询中大小和 mtime 保持稳定），因此不会扫描到写入一半的下载文件。监控器会复用您配置的任何引擎，并跳过其自身的隔离保险库。 ## Web 仪表板一个带有主题的 Flask UI，用于扫描路径、查看判定结果和管理隔离区。 ``` pip install flask python serve.py # http://127.0.0.1:8080 ``` ## VirusTotal 查询（可选）将每个文件与 [VirusTotal](https://www.virustotal.com) 汇总的杀毒软件判定结果进行交叉比对。它是**可选的**且**注重隐私的**：只发送文件的 SHA-256 **哈希**，绝不发送其内容。如果 VT 从未见过该哈希，则不会泄露关于您文件的任何信息。 ``` # 在 virustotal.com 获取免费的 API key，然后： export VT_API_KEY=your_key_here # PowerShell: $env:VT_API_KEY="your_key_here" python -m malscan scan ./downloads --virustotal ``` 判定结果根据 VT 的引擎共识进行映射：>=3 个引擎报恶意 -> `malicious`， 1-2 个 -> `suspicious`，已知且安全 -> `info`，未知 -> 无发现。免费层级允许每分钟查询 4 次，因此这最适合用于扫描少量文件。 ## 机器学习分类器（可选）如果说启发式引擎编码的是分析师手写的规则，那么 ML 引擎则从带标签的语料库中*学习*权重 —— 这是现代 AV 用来捕获没有特征码的新型样本的方法。它从每个文件中提取紧凑的特征向量（整体文件熵、字节分布统计，加上 PE 节/导入结构），并使用逻辑回归模型对其进行评分。它是**可选的且受模型限制的**，就像 VirusTotal 引擎一样：不捆绑任何模型，且扫描绝不会隐式加载模型。您可以在自己带标签的数据上进行训练。**推理过程完全使用标准库**（模型是一个包含权重的小型 JSON），因此即使在无依赖的冻结二进制文件中，训练好的模型依然可以对文件进行评分。 ``` # 1. 在两个包含已知安全和已知恶意文件的文件夹上进行训练。 # 对于真实模型，将 --malicious 指向恶意软件语料库，例如 # EMBER 数据集 (https://github.com/elastic/ember) 的子集；请将样本保存在 VM 中。 python -m malscan ml-train --benign ./clean --malicious ./malware -o ml_model.json # 2. 使用它进行扫描。 python -m malscan scan ./downloads --ml-model ml_model.json # 或者将其放置在 signatures/ml_model.json 并直接传入 --ml ``` 由于是推理而非特征码，ML 引擎最多只会引发 `suspicious` 判定，并报告模型的概率，供人工权衡。内置的训练器是一个易于理解的基础版本（通过梯度下降实现逻辑回归）；特征提取器和评分接口的形态与生产级梯度提升流水线所使用的相同，因此它是一个忠实且可重训练的起点 —— 而不是一个预训练的生产级检测器。 ## 本地信誉缓存（可选）商业 AV 会将世界上前所未见的文件与在数百万台机器上运行的文件区别对待 —— 稀有性就是一种信号（“首见即拦截”）。您无法单枪匹马地复制一个全球遥测网络，但您*可以*保留一份**本地** 流行度记录。通过 `--reputation`，malscan 会将每个扫描过的哈希记录到一个小型 SQLite 缓存中，并在首次在此主机上看到**可执行文件**时引发 `info` 发现： ``` python -m malscan scan ./downloads --reputation # record + flag unknowns python -m malscan reputation # show cache statistics ``` 它是**可选的**，仅在启用时才进行写入，因此核心功能和公开的 Web 演示保持无状态。这是云信誉在单主机上真实的一个切片 —— *机制*（基于流行度的怀疑），其作用范围仅限于一台机器所能知道的内容。 ## AI 分诊（可选）让 Claude 将 malscan 的发现转化为通俗易懂的英文分析报告 —— 说明每次检测的可能含义、可信度以及后续操作建议。 ``` pip install anthropic export ANTHROPIC_API_KEY=sk-ant-... # PowerShell: $env:ANTHROPIC_API_KEY="sk-ant-..." python -m malscan triage ./downloads # triages suspicious-or-worse files ``` **隐私优先设计**（与 VirusTotal 引擎的原则相同）：分诊仅发送扫描*元数据* —— 判定结果、引擎发现、规则名称、熵评分、哈希以及文件的基本名称。**绝不发送文件内容**，并且完整的文件系统路径在离开您的机器之前会被剥离为基本名称。使用 Anthropic SDK 和 `claude-opus-4-8` 并结合自适应思考，结果流式传输到您的终端。可选，且仅限 CLI —— 绝不会接入公开的 Web 演示中。 ## 路线图 - [x] 隔离保险库（隔离并恢复被标记的文件） - [x] Flask Web 仪表板（主题化，支持 Render 部署） - [x] 可选的 VirusTotal 哈希查询 - [x] HTML 报告输出 - [x] 基于发现结果的 AI 分诊 (Claude) - [x] 在发现结果上进行 MITRE ATT&CK 技术标记（CLI、报告、仪表板） - [x] 文件类型伪装检测（Magic bytes 与扩展名比对） - [x] 用于 GitHub 代码扫描的 SARIF 输出 - [x] ML 分类器（可训练的逻辑回归引擎，标准库推理） - [x] 实时文件夹监控（用户空间访问时扫描） - [x] 逻辑多条件签名（ClamAV `.ldb` 风格的布尔规则） - [x] 本地文件信誉缓存（首次发现/流行度标记） ## License MIT

标签：DNS 反向解析, PE分析, YARA, 云资产可视化, 恶意软件扫描, 本地防护, 漏洞挖掘, 逆向工具