ChristianPresley/yara-forge-ci

# yara-forge-ci **将规则即代码应用于检测工程。** 一个小巧、独立的 YARA 规则 仓库，封装在 CI/测试框架中，该框架会编译每一条规则，强制执行 元数据策略，针对标记为阳性/阴性的语料库测试每条规则，并 防范性能衰退——就像你将应用于 应用代码的规范一样，应用于检测内容。 [](.github/workflows/ci.yml)   ## 为什么会有这个项目 检测规则会在不知不觉中失效。上一季度还能编译通过的规则，可能会在 YARA 升级后开始抛出警告；为了减少误报而进行的“快速修复” 可能会悄悄地扼杀一个真正的阳性（true positive）；偷懒编写的 正则表达式可能会耗尽整个 集群的扫描时间预算。在威胁情报 / 检测工程的背景下，规则*本身*就是 产品——因此它理应得到我们给予生产代码的同等保障：版本 控制、自动化测试、审查工作流，以及在失败时能大声报错的 CI。 本仓库是这一理念的精简参考实现。每一条规则都附带了一个 证明它能触发的阳性样本，并针对良性软件（goodware）语料库进行了测试，以证明它不会过度触发。这里的一切都不需要真实的恶意软件： 所有的触发样本都是手工制作的、惰性的、合成的测试用例。 ## 包含的内容 ``` yara-forge-ci/ ├── rules/ # 10 original YARA rules, one detection idea each ├── tests/ │ ├── samples/ │ │ ├── positive/ # inert fixtures that SHOULD match a specific rule │ │ └── negative/ # goodware / FP corpus that must match NOTHING │ ├── mapping.yml # sample -> expected-rule map + perf budget │ └── test_rules.py # pytest harness (compile/policy/TP/FP/perf) ├── scripts/ │ └── validate.py # `yforge` CLI dashboard for local iteration ├── .github/workflows/ci.yml # ruff lint + harness on every push/PR ├── pyproject.toml # deps, ruff + pytest config ├── requirements.txt ├── LICENSE # MIT (c) 2026 Christian Presley └── README.md ``` ### 规则集 | 规则 | 检测思路 | ATT&CK | 严重程度 | |------|----------------|--------|----------| | `PowerShell_EncodedCommand` | PowerShell `-enc`/`-EncodedCommand` Base64 载荷 | T1059.001 | high | | `PowerShell_DownloadCradle` | 内存中下载并执行的 cradle（`IEX (New-Object Net.WebClient)...`） | T1059.001 | high | | `PowerShell_AMSI_Bypass` | 反射式 AMSI 篡改（`amsiInitFailed`，`AmsiScanBuffer` 补丁） | T1562.001 | critical | | `Webshell_PHP_Eval_Base64` | PHP webshell：通过 `base64_decode($_POST[...])` 传入的 `eval`/`assert` | T1505.003 | high | | `Webshell_ASPX_CodeExec` | ASPX/JScript webshell，包含中国菜刀 `eval(Request.Item[...])` | T1505.003 | high | | `Phishing_Kit_CredHarvest_HTML` | 带有发往外部 POST + base64 第二阶段的静态凭据收集页面 | T1566.002 | medium | | `LNK_ScriptHost_Dropper` | 生成隐藏脚本宿主的快捷方式/容器 dropper | T1204.002 | high | | `Base64_Encoded_PE_Heuristic` | 以 Base64 blob 形式嵌入在文本载体中的 Windows PE | T1027 | medium | | `LLM_Jailbreak_PromptInjection` | 不可信文本中已知的越狱（jailbreak）/ 提示词注入（prompt-injection）载荷 | T1204 | medium | | `Ransomware_Note_Template` | 勒索信特征（加密声明 + 支付渠道 + 威胁） | T1486 | high | 最后两条规则特意侧重于 **AI 滥用检测**——扫描 不可信文本（RAG 语料库、上传文件、支持工单）以寻找提示词注入（prompt-injection） 载荷，并捕获无论是手写还是 LLM 生成的勒索信。这两者都 正是 AI 实验室所关心的内容滥用信号，并且都可以 在没有任何真实恶意软件的情况下进行演示。 ## 每条规则必须满足的三个契约 **1. 元数据策略（治理）。** 每条规则都必须包含完整的 meta 块： ``` author, date, description, reference, mitre_attack, severity, version ``` `severity` 必须是 `low | medium | high | critical` 之一。测试框架会 从*已编译*的规则中读取元数据（而不是通过抓取文本），因此该策略无法 通过注释来伪造。缺失或为空的字段会导致构建失败。这使得 规则集具备自我记录的能力，并允许下游工具基于 ATT&CK id / 严重程度进行关联。 **2. 阳性与阴性语料库（准确性）。** - `tests/samples/positive/` —— 每个文件都是为了 恰好触发一条规则而精心制作的最小的、惰性的样本。`tests/mapping.yml` 记录了哪个样本必须匹配哪条 规则。没有阳性样本的规则会导致**覆盖率门禁**失败。 - `tests/samples/negative/` —— 良性的正常软件（一个管理用的 PowerShell 脚本，一个真实的 联系表单处理器，一个带有密码字段且合法的登录页面，安全 博客文本，一个带有类似 `TVpQ` token 的配置文件）。在这里**任何**匹配都是 误报，并会导致构建失败。有几个阴性样本是故意设计的对抗性样本—— 例如，良性的登录页面带有密码字段和 POST 表单，因此它 证明了钓鱼规则的附加条件确实抑制了容易产生的误报（FP）。 **3. 性能预算（成本）。** 每条规则都会（取 3 次中最好的成绩）针对完整的 语料库进行计时，并且必须保持在 `mapping.yml` 中设定的单条规则预算之内（默认为 50 ms）。 这是尽早发现糟糕正则表达式的地方。这些规则本身在编写时就考虑了 性能感知：字符串原子（atom）长度 ≥ 4 字节以实现强大的 Aho-Corasick 匹配， 正则表达式量词是有界的（使用 `.{0,64}` 而不是 `.*`）以避免灾难性 回溯，并且通用 token（如 `eval`、`cmd`）仅用作 辅助条件，绝不会作为唯一的触发条件。 ## 设置与使用 ``` # 1. Install (a C toolchain may be needed to build yara-python from source; # most platforms have prebuilt wheels). python -m pip install -r requirements.txt # 2. Local dashboard — fast, colorized, per-rule status. Great for iterating. python scripts/validate.py # 3. Full CI harness — the authoritative gate (also run in GitHub Actions). pytest -v # 4. Lint the Python. ruff check . ``` `scripts/validate.py` 会打印出每条规则的表格（编译 / 元数据 / 真阳性 / 误报数 / 扫描时间与预算对比），并在出现任何失败时以非零状态退出， 因此它既可以作为人类查看的仪表盘，也可以作为 CI 的门禁。 ## 添加新规则（贡献工作流） 1. **编写规则**，放在 `rules/.yar` 中，包含完整的 meta 块（所有七个 必需的键）。优先使用长且具体的原子；为每个正则表达式量词设定边界。 2. **添加一个阳性样本**到 `tests/samples/positive/` 中 —— 能够合理触发 该规则的最小惰性文件。将其标记为 `SYNTHETIC TEST FIXTURE`。 3. **在 `tests/mapping.yml` 的 `expected_matches` 下注册它**。 4. **对良性软件语料库进行合理性检查。** 如果你的规则有可能产生误报（FP），请在 `tests/samples/negative/` 中添加一个具有代表性的良性文件，这样防护才 是真实有效的。 5. **运行 `python scripts/validate.py` 和 `pytest`**，直到全部通过（变绿），然后提交 PR。 CI 会在推送时重新运行所有内容。 覆盖率门禁确保没有规则能在缺少阳性样本的情况下被合并，而 误报（FP）防护则确保其通过了良性软件的测试。 ## 未来工作 / 说明 - **YARA-X。** VirusTotal 在 2025 年用 Rust 重写的引擎（[YARA-X](https://virustotal.github.io/yara-x/)） 是未来的发展方向：更快的扫描速度，更严格/更清晰的规则语义， 以及维护良好的 `yara-x-py` 绑定。该框架目前故意使用了成熟的 `yara-python`（libyara）绑定，以实现最大的可移植性，但其设计是 引擎无关的——迁移工作主要就是替换 `compile`/`match` 调用并 重新基线化性能预算。在 CI 中增加一条 `yara-x` 矩阵分支是顺理成章的下一步， 此外还要对正则表达式量词语法进行兼容性检查。 - **更丰富的语料库。** 阴性语料库可以扩展成为一个正规的正常软件集 （常见脚本、安装程序、框架文件），以强化误报（FP）防护。 - **规则打包。** 在带标签的发布版本中生成一个已签名、带版本号的规则集包。 - **覆盖率报告。** 将 ATT&CK 技术覆盖率以生成的矩阵形式展示出来。 ## 许可证 MIT © 2026 Christian Presley。请参阅 [LICENSE](LICENSE)。 本仓库中的所有样本都是合成的、惰性的，并且都有明确的标签。本 项目**不**包含任何恶意软件，运行它也**不需要**任何恶意软件。

标签：YARA, 云资产可视化, 安全规则引擎, 逆向工具