Danush-Aries/yaratune
GitHub: Danush-Aries/yaratune
yaratune 通过自动化的误报调优循环和精确率/召回率证据报告，解决了传统 YARA 规则生成器缺乏验证、误报率高且已停止维护的问题。
Stars: 1 | Forks: 0
# yaratune
**从真实的恶意软件与良性语料库中生成 YARA 规则，针对良性语料库自动进行调优直至误报降至零，并输出包含精确率/召回率的测试证据报告。**
检测工程领域存在一个工具空白。作为该领域的王者，[yarGen](https://github.com/Neo23x0/yarGen)（1.8k★）**自 2020 年 12 月以来就停止维护了** —— 它属于 Python-2 时代，缺乏误报调优循环，并且无法为其生成的规则提供足以证明可安全部署的证据。其他自动化的 YARA 生成器要么是学术原型，要么已经名存实亡。
没有人提供检测工程师真正需要的核心功能：**迭代式的良性语料库 FP（误报）调优循环，外加一份精确率/召回率测试报告。** 这正是 yaratune 填补的空白。它的目标不仅仅是“生成一条规则”，而是**生成、调优至零误报，并加以_证明_**。
yaratune 会对**真实**文件进行**真正**的分析：真实的字节/字符串提取（ASCII + UTF-16LE，以及通过 `pefile` 获取的 PE 元数据），并通过 `yara-python` 进行真实的 YARA 编译和扫描。它是完全离线的——无需 API 密钥，不连云服务，且**不需要真实的恶意软件**（内置的演示语料库是 100% 合成且安全的）。
## 为什么它与众不同
| | yarGen | 学术工具 | **yaratune** |
| --- | --- | --- | --- |
| 从真实字节中提取真实字符串 | 是 | 是 | **是** |
| 通过恶意与良性的区分度进行评分 | 部分 | 视情况而定 | **是（TF-IDF 风格）** |
| **迭代式良性 FP 调优循环** | **否** | **否** | **是** |
| **精确率/召回率证据报告** | **否** | **否** | **是（MD 和 JSON）** |
| 维护状态 | **自 2020 年起废弃** | 名存实亡 | **是** |
## 快速开始
```
# yara-python 为 CPython 3.9–3.12 提供了 wheels。请使用 3.11/3.12 venv。
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]" # runtime + pytest; docs below
# 生成 + 调优 + 验证，基于内置的 SAFE 合成语料库
yaratune gen examples/mal --benign examples/benign --out examples/generated.yar
```
这会在其同级目录下生成一条调优过的 `.yar` 规则以及 `report.md` / `report.json`，并打印出证据。在内置的语料库上，它实现了**对 100% 恶意软件家族的检测，同时保持 0 误报**，这是在该循环消除了 **8** 个基线误报之后达到的效果。
运行测试：
```
pip install -e ".[dev]" # installs the [dev] extra (pytest)
pytest # 34 tests, all green
```
预留出部分家族样本，以证明该规则具备**泛化**能力，而不仅仅是死记硬背：
```
yaratune holdout examples/mal --benign examples/benign --holdout 2
# holdout recall: 100.0% holdout FP: 0
```
## 生成的规则示例
```
rule yaratune_mal
{
meta:
author = "Dhanush Shankar"
description = "Auto-generated + FP-tuned rule for yaratune_mal"
malware_samples = 6
benign_samples = 8
date = "2026-07-02"
generator = "yaratune"
strings:
$s0 = "YOUR FILES HAVE BEEN ENCRYPTED - pay 0.5 BTC to recover" ascii wide
$s1 = "hxxp://evil-c2-panel.example.onion/gate.php" ascii wide
$s2 = "Global\\R4nZ0m_MUTEX_9f3a17bc" ascii wide
$s3 = "xor_key=0xDEADBEEFCAFEBABE" ascii wide
$s4 = "R4nZ0m_family_build_2026" ascii wide
condition:
all of them
}
```
上方的每一个字符串都是独特的家族标志物。那些天真的频率优先生成器通常会包含的通用 Windows API 样板代码（如 `kernel32.dll`、`LoadLibraryA`、`GetProcAddress` 等）都被**调优剔除**了，因为它们同样存在于正常软件中。
### …及其测试证据
| 指标 | 数值 |
| --- | --- |
| 受测恶意软件样本 | 6 |
| 受测良性样本 | 8 |
| 真阳性 / 假阴性 | 6 / 0 |
| 假阳性 / 真阴性 | 0 / 8 |
| **精确率 (Precision)** | **100.0%** |
| **召回率 (Recall)** | **100.0%** |
| 误报率 (FP rate) | 0.0% |
| F1 分数 | 1.0000 |
**FP 调优循环** — 基线误报：**8** → 最终：**0**（已收敛）：
| 迭代次数 | 字符串数量 | 条件 | 良性 FP | 丢弃的项 |
| --- | --- | --- | --- | --- |
| 0 | 17 | 包含其中 1 个 | 8 | _基线（天真模式，未调优）_ |
| 1 | 16 | 包含其中 1 个 | 8 | `This program cannot be run in DOS mode.` |
| … | … | … | … | … |
| 10 | 7 | 包含其中 1 个 | 7 | `advapi32.dll` |
| 11 | 6 | 包含其中 1 个 | 5 | `LoadLibraryA` |
| 12 | 5 | 包含其中 1 个 | 0 | `kernel32.dll` |
| 13 | 5 | **全部包含** | 0 | _收紧条件_ |
## 调优循环的工作原理
1. **加载与提取。** 读取每个样本的真实字节；提取 ASCII + UTF-16LE 字符串（当文件是 PE 时，还会提取 PE 元数据）。
2. **评分与选择。** 对于每个候选字符串，计算其在恶意软件与良性软件中的文档频率。选择得分将区分度 `mal_freq − ben_freq` 与 TF-IDF 风格的 IDF 项（用于抑制无处不在的样板代码）以及轻微的长度加成相结合。**基线**经过刻意设计，采用频率优先原则，因此它包含了与良性软件共有的样板代码——这正是天真的生成器所输出的内容。
3. **合成。** 生成有效的 YARA 规则（`meta` / `strings` / `condition`）。可打印字符串会变为带引号的 `ascii wide` 文本字符串；任何不可打印的内容都会以 `{ hex }` 字符串的形式输出，因此支持任意的二进制标志物。
4. **调优至零 FP。** 编译规则，扫描**良性**语料库，只要有良性样本匹配，就剔除对这些匹配影响最大的字符串（良性频率最高的优先剔除）。家族标志物永远不会出现在正常软件中，因此它们绝不会被剔除，整个过程中的训练召回率始终保持在 100%。每次迭代都会被记录下来。
5. **强化。** 将条件收紧为最强有力的 `N of them` 阈值，且该阈值仍需匹配每一个训练用的恶意软件样本。
6. **证明。** 用调优后的规则扫描带标签的语料库，并以 Markdown **和** JSON 格式输出精确率 / 召回率 / FP 率 / 混淆矩阵。
可选：`--ollama-name` 会运行一个**本地**的 Ollama 模型（默认关闭，无需密钥，仅限 `localhost`）来建议规则名称；如果 Ollama 未运行，它会静默回退到确定性的命名方式。
## 演示语料库（100% 合成，100% 安全）
`examples/build_corpus.py` 制造了演示数据——**本仓库中不包含真实的恶意软件。** 它创建了：
- 一个由共享独特伪造标志物（伪造的 `.onion` C2、伪造的互斥锁、伪造的勒索说明片段、伪造的 XOR 密钥）的小型类 PE 二进制文件组成的玩具级“恶意软件家族”，以及
- 一个良性语料库，包含相同的通用 Windows API 样板代码，但**不包含**任何上述标志物。
这种重叠是有意为之的：它使得天真的基线规则会在良性文件上触发，从而为 FP 调优循环提供真正需要消除的误报。所有数据都设置了种子，完全可复现：
```
python examples/build_corpus.py # or: ./examples/build_corpus.sh
```
## 安装注意事项 (yara-python)
`yara-python` 为 CPython **3.9–3.12** 提供了预构建的 wheel 包。在本项目中，它在 **Python 3.11** 虚拟环境中干净利落地安装了 `yara-python 4.5.4`。如果你默认的 `python3` 是 3.13/3.14，可能还没有对应的 wheel 包——请使用 `python3.11`/`python3.12` 创建虚拟环境，或者安装原生的 `yara` 工具链以便扩展程序能够编译。`pefile` 是纯 Python 库，总是能够顺利安装。
开发安装（明确记录如下）：`pip install -e ".[dev]"` 会通过 `[dev]` 可选依赖项拉取 `pytest`。
## 局限性与客观评价
- 内置的语料库是**合成的**。它清晰地展示了该方法；但这并不是针对真实世界恶意软件家族的基准测试。
- 生成的规则是**分析师的起点，不能替代分析师的审查。** 真实的语料库更加杂乱——加壳、多态以及共享代码家族都会使字符串选择变得复杂。
- 零 FP 是**针对您提供的良性语料库**衡量的。规则的好坏仅取决于您用来测试它的正常软件；请扩大良性样本集以获得更强的保证。
- yaratune 目前生成的是基于字符串的规则；它（目前）还不能合成 `pe.*` 模块条件、imphash 或 opcode 模式。
## 伦理声明
yaratune 是一款**防御性**的检测工程工具。它不附带任何恶意软件、漏洞利用代码或攻击能力。演示用的标志物明显是伪造的。请使用它为您获得授权进行分析的正常软件构建和验证检测规则。
## 许可证
MIT © 2026 Dhanush Shankar。专为检测工程/安全实习作品集而构建。
标签：AI风险缓解, AMSI绕过, DAST, DNS 反向解析, YARA, 云计算, 云资产可视化, 威胁检测, 安全规则引擎, 恶意软件分析, 特征工程, 规则引擎, 逆向工具