PSubutai/yara-scan
GitHub: PSubutai/yara-scan
一款专注于 Windows 的命令行 YARA 扫描工具，支持实时进度显示、文件元数据富化、归档扫描及 YARA Forge 规则自动更新。
Stars: 0 | Forks: 0
yara-scan
专注于 Windows 的命令行 YARA 扫描工具
扫描单个文件或目录树，通过文件类型检测（`python-magic-bin`）、MD5/SHA256 哈希以及 PE 头/导入元数据（`pefile`）来丰富匹配结果，并将结果报告到控制台和/或 text/JSON/HTML 文件中。
## 运行示例
```
Found 310 file(s) to scan under C:\Downloads\suspicious
(001/310) [clean] C:\Downloads\suspicious\setup.exe
(002/310) [clean] C:\Downloads\suspicious\readme.txt
(003/310) [MATCH] C:\Downloads\suspicious\payload.dll
- TRELLIX_ARC_Malw_Eicar [high] (EICAR)
(004/310) [clean] C:\Downloads\suspicious\data.json
[##############################] 310/310 (100%)
Scanned 310 file(s): 1 matched, 1 total rule hit(s), 0 error(s)
```
每个文件的扫描结果会在扫描完成的瞬间流式输出到控制台——中间带有实时进度条——而不是等到整个扫描结束后才静默显示。
## 功能
- **扫描文件或整个目录树**，默认递归扫描
- **实时逐文件控制台输出**，带有进度条，并在扫描过程中自动编号和颜色标记
- **文件类型检测**（`python-magic-bin`）、MD5/SHA256 哈希计算，以及 PE 头/导入/节元数据提取（`pefile`）
- **归档扫描**，支持扫描 `.zip` 文件内部，并具备 zip bomb 防护机制（深度 + 大小限制）
- **Text / JSON / HTML 报告**，作为控制台输出的补充
- **内置 [YARA Forge](https://yarahq.github.io/) 规则更新器** ——
`update-rules.py` 只需一条命令即可拉取经过精选、去重的公共规则集，后续还能检查并应用更新的版本
- **多线程支持**，带有已编译规则的缓存机制，避免重复扫描时重新编译
## 安装说明
```
.venv\Scripts\python.exe -m pip install -r requirements.txt
```
将 `.yar`/`.yara` 规则文件放入 `rules/` 目录（来源详见 `rules/README.md`），或者使用 `-r` 指定其他文件夹/文件。要快速开始，请拉取精选的 [YARA Forge](https://yarahq.github.io/) 规则集：
```
python update-rules.py
```
## 用法
```
yara-scan.py TARGET [options]
```
`TARGET` 可以是文件或目录（默认递归扫描）。
### 示例
```
# 扫描单个文件
python yara-scan.py C:\Downloads\input.exe
# 递归扫描目录，仅将结果打印到控制台
python yara-scan.py C:\folder
# 扫描目录并将文本 + JSON + HTML 报告写入文件夹
python yara-scan.py C:\folder -o C:\output_folder -f text -f json -f html
# 使用特定的 rules 文件代替默认的 rules/ 文件夹
python yara-scan.py input.exe -r C:\my_rules\suspicious.yar
# 跳过 archives，限制线程数，排除嘈杂路径
python yara-scan.py C:\folder --no-archive-scan -j 4 -x "*\node_modules\*"
# 列出当前已加载的 rules
python yara-scan.py --list-rules
```
### 主要选项
| 标志 | 用途 |
|---|---|
| `-r/--rules PATH` | 规则文件夹或单个 `.yar`/`.yara`/`.yrc` 文件（默认：`rules/`） |
| `-o/--output-dir DIR` | 指定报告文件的写入目录 |
| `-f/--format {text,json,html}` | 可多次指定；写入到 `-o` 的格式（默认：text） |
| `--no-recursive` | 仅扫描目录的顶层 |
| `-x/--exclude PATTERN` | 可多次指定的 glob 排除模式 |
| `--include-ext .exe,.dll` | 扩展名白名单 |
| `--max-size SIZE` | 跳过大于此大小的文件（`100MB`、`2GB` 等） |
| `-j/--threads N` | 工作线程数（默认：CPU 核心数） |
| `--archive-scan/--no-archive-scan` | 扫描 `.zip` 文件内部（默认：开启） |
| `--max-archive-size`、`--archive-depth` | Zip bomb 防护机制 |
| `--hash {md5,sha256,both,none}` | 指定要计算的哈希值（默认：both） |
| `--no-pe-info` | 跳过 PE 头/导入/节解析 |
| `--show-strings` | 包含匹配的字符串片段（速度较慢——会禁用 YARA 快速匹配） |
| `--timeout SECONDS` | 单个文件的 YARA 匹配超时时间 |
| `--external KEY=VALUE` | 为规则提供额外的外部变量（可多次指定） |
| `--list-rules` | 打印已加载的规则名称并退出 |
| `-v/--verbose`、`-q/--quiet`、`--no-color` | 输出控制 |
完整列表：`python yara-scan.py -h`
规则可以引用自动提供的外部变量 `filepath`、`filename`、`extension` 和 `filesize`，例如：
```
rule big_exe { condition: extension == ".exe" and filesize > 5MB }
```
### 退出代码
- `0` — 扫描完成，无匹配
- `1` — 扫描完成，至少有一个匹配
- `2` — 错误（目标/规则路径无效、规则编译失败、参数无效）
## 保持规则更新
`update-rules.py` 会下载/更新 [YARA Forge](https://yarahq.github.io/) 规则包到 `rules/yara-forge/` 目录，并在安装前根据 GitHub 发布的 SHA256 校验码验证每次下载：
```
python update-rules.py # install/update the "core" tier (default)
python update-rules.py --tier extended # switch tiers (core/extended/full)
python update-rules.py --check # check only; exit code 1 means an update is available
python update-rules.py --force # reinstall even if already current
python update-rules.py --dest DIR # install somewhere other than rules/yara-forge/
```
切换层级（tier）时会自动先删除之前已安装层级对应的文件，因此绝不会出现两个重叠层级被一起编译的情况。
`--check` 专为计划任务设计——退出代码 `0` 表示已是最新，`1` 表示存在更新的版本，`2` 表示 GitHub API/下载失败。
关于各层级之间的权衡以及其他规则来源，请参阅 `rules/README.md` 获取更多信息。
## 注意事项
- **`magic` 与 `pe` 模块**：预编译的 Windows `yara-python` wheel 不包含 YARA 自带的 `magic` 模块（因为它需要 `libmagic`），这就是为什么此处的文件类型检测是通过 Python 中的 `python-magic-bin` 完成的，而不是在 `.yar` 规则条件内部实现。YARA 内置的 `pe` 模块依然可以像往常一样在规则条件中正常使用（例如 `pe.is_dll()`）；由于 YARA 无法将这些数据返回给 Python，本工具单独使用 `pefile` 在报告中展示 PE 的详细信息（导入表、节区、入口点等）。
- 归档扫描目前仅支持 `.zip` 格式，并带有深度限制（默认为 1——即不会打开嵌套在 zip 内部的 zip）和大小上限，以防止 zip bomb。
- 已编译的规则会缓存在 `
/.cache/` 目录下，并在任何规则文件的路径/大小/修改时间（mtime）发生变化时自动失效。
## 暂未包含（未来可能添加的功能）
- `--pid` 进程内存扫描
- 隔离/移动匹配文件的操作（本工具仅用于生成报告——它绝不会修改或移动被扫描的文件）
- VirusTotal 哈希富化
## 许可证
[MIT](LICENSE)标签：AMSI绕过, DNS 反向解析, Python, YARA, 云资产可视化, 威胁检测, 恶意软件扫描, 无后门, 网络信息收集, 逆向工具