marez8505/YARAForge
GitHub: marez8505/YARAForge
纯 Python 实现的 YARA 规则引擎与恶意文件扫描器，从零构建解析器和匹配器，内置数十条检测规则并支持自动规则生成与取证报告输出。
Stars: 0 | Forks: 0
# YARAForge
[](https://www.python.org/downloads/)
[](LICENSE)
[](yaraforge/engine/)
[](yaraforge/rules/)
[](https://github.com/marez8505)
## 什么是 YARA？
YARA 是恶意软件分类和失陷指标检测的事实标准。
YARA 由 VirusTotal 的 Victor Alvarez 创建，允许分析人员根据**文本或二进制模式**编写描述恶意软件家族的规则——从作者忘记剔除的特定字符串，到加密例程的字节级签名，无所不包。
### 为什么 YARA 很重要
每个严谨的安全团队都在使用 YARA：
| 组织 | 如何使用 YARA |
|---|---|
| **VirusTotal** | 使用数千条社区规则扫描每个上传的文件 |
| **CISA / US-CERT** | 在安全公告中发布用于威胁狩猎的 YARA 规则 |
| **MITRE ATT&CK** | 将 YARA 与 ATT&CK 技术结合使用以进行行为映射 |
| **EDR 供应商** | CrowdStrike、SentinelOne、Carbon Black 都在内部使用 YARA |
| **SOC/IR 团队** | 在安全事件期间在企业端点中狩猎 APT IOC |
| **恶意软件研究人员** | 通过共享的代码模式对恶意软件家族进行分类和聚类 |
一条查找 `"vssadmin delete shadows"` 并包含 `"CryptEncrypt"` 的规则，可以检测到即使网络基础设施发生改变，但共享行为代码的勒索软件家族——这是基于哈希的检测无法做到的。
## 功能
- **纯 Python YARA 引擎** — 无需编译的 C 扩展。从零开始实现了 YARA 规范：规则解析、字符串匹配（text/hex/regex）和条件评估。这比仅仅做一个库的封装更令人印象深刻。
- **48+ 条生产级规则** — 按恶意软件家族和技术进行分类组织，使用真实的模式和 MITRE ATT&CK 映射编写。
- **规则生成器** — 将 YARAForge 指向一个可疑二进制文件，它会提取唯一的字符串、字节模式和熵特征，自动起草新规则。
- **规则验证器** — 检查规则是否存在语法错误、过于宽泛的条件、容易引起误报的短字符串以及性能反模式。
- **取证报告** — 暗色主题的 HTML 报告，包含严重性分布、匹配的字符串偏移量、文件元数据（MD5/SHA-256/entropy）以及 MITRE ATT&CK 参考。
- **CLI 接口** — 包含 `scan`、`generate`、`validate`、`list`、`report`、`demo` 命令。
## 架构
```
YARAForge/
│
├── yaraforge/
│ ├── engine/ ← Pure Python YARA engine
│ │ ├── rule_parser.py Rule lexer + recursive-descent parser
│ │ ├── rule_compiler.py Pre-compiles patterns for fast scanning
│ │ ├── matcher.py File scanner: runs rules against bytes
│ │ ├── condition_evaluator.py Pratt parser for condition expressions
│ │ └── string_matcher.py Boyer-Moore text + hex/regex matching
│ │
│ ├── rules/ ← YARA rule library (48+ rules)
│ │ ├── malware/ Ransomware, Trojans, RATs, Miners
│ │ ├── techniques/ Packers, Shellcode, PowerShell, Persistence
│ │ ├── file_types/ PE/ELF, Documents, Scripts
│ │ └── indicators/ IOCs, Crypto wallets, Data theft
│ │
│ ├── rule_generator.py Auto-generates rules from samples
│ ├── rule_validator.py Validates rule quality and syntax
│ ├── scanner.py Orchestrates scanning operations
│ ├── report_generator.py HTML + JSON forensic reports
│ └── utils.py Entropy, hashing, string extraction
│
├── sample_files/ ← Synthetic test samples
├── tests/ ← Unit tests
└── README.md
```
**数据流:**
```
.yar files ──► RuleParser ──► YARARule objects
│
RuleCompiler
│
CompiledRule objects
│
File(s) ──► Matcher ──► StringMatcher + ConditionEvaluator ──► RuleMatch list
│
ReportGenerator ──► HTML/JSON
```
## 安装
```
git clone https://github.com/marez8505/YARAForge.git
cd YARAForge
pip install -r requirements.txt
```
**环境要求:** Python 3.8+ | `jinja2`（仅用于 HTML 报告）
## 快速入门
```
# 运行 demo
python -m yaraforge demo
# 扫描可疑文件
python -m yaraforge scan --target ./malware_sample.exe
# 递归扫描目录
python -m yaraforge scan --target ./evidence/ --recursive --output ./reports/
# 从 sample 生成规则
python -m yaraforge generate --sample ./suspicious.bin --output ./new_rule.yar
# 验证所有规则
python -m yaraforge validate --rules ./yaraforge/rules/
# 列出所有规则
python -m yaraforge list --rules ./yaraforge/rules/ --format table
```
## CLI 参考
### `scan`
```
python -m yaraforge scan --target [options]
Options:
--rules, -r Rules file or directory (default: built-in rules)
--recursive, -R Recursively scan subdirectories
--output, -o Output directory for HTML/JSON reports
--max-size Maximum file size in MB (default: 50)
--quiet, -q Suppress matched string details
```
**示例输出:**
```
[*] Loading rules from: yaraforge/rules/
[+] Loaded 48 rules
[*] Scanning: evidence/
------------------------------------------------------------
[*] Scanned 12 files (3 matches) @ 45 files/s
[+] Scan complete in 0.27s
Files scanned: 12
Matches found: 3
MATCHES:
------------------------------------------------------------
[CRITICAL ] Ransomware_Generic_Encryption_Behavior
File: readme.bin (2.1 KB)
Desc: Detects generic ransomware encryption behavior
MITRE: T1486 - Data Encrypted for Impact
Matched strings:
$note1 @ 0x00000004: 'README_TO_DECRYPT'
$api1 @ 0x00000041: 'CryptEncrypt'
$shadow1 @ 0x00000067: 'vssadmin delete shadows'
[HIGH ] Webshell_PHP_Generic
File: shell.php (512 B)
Desc: Detects PHP web shells via command execution functions
```
### `generate`
```
python -m yaraforge generate --sample ./suspicious.bin --output ./rule.yar
Options:
--name, -n Rule name (auto-derived from filename if omitted)
--author, -a Author name (default: Edward Marez)
```
**生成的规则示例:**
```
/*
* Auto-generated YARA rule by YARAForge
* Source file: suspicious.bin
* Generated: 2026-03-31 14:23:01 UTC
* File type: PE Executable
* Entropy: 6.8421 (high (possibly packed))
* MD5: a1b2c3d4e5f6...
*/
rule Generated_suspicious : generated pe {
meta:
author = "Edward Marez"
description = "Auto-generated rule from sample: suspicious.bin"
date = "2026-03-31"
severity = "unknown"
strings:
$hex_1 = { 4D 5A 90 00 03 00 00 00 04 00 00 00 FF FF 00 00 }
$s1 = "CreateRemoteThread" // Score: 5, offset: 0x2A0
$s2 = "VirtualAllocEx" // Score: 5, offset: 0x2B4
$s3 = "WriteProcessMemory" // Score: 4, offset: 0x2C8
condition:
uint16(0) == 0x5A4D and
filesize > 1024 and filesize < 20971520 and
$hex_1 at 0 and
2 of ($s*)
}
```
## 规则库
| 类别 | 文件 | 规则数 | 描述 |
|---|---|---|---|
| **Malware** | `ransomware.yar` | 5 | 加密行为，WannaCry，Ryuk，LockBit |
| **Malware** | `trojans.yar` | 5 | 通用 RAT，AsyncRAT，njRAT，反向 shell，释放器 |
| **Malware** | `cryptominers.yar` | 3 | XMRig，Stratum 协议，JS 浏览器挖矿程序 |
| **Malware** | `webshells.yar` | 4 | PHP，China Chopper，ASPX，JSP Web Shell |
| **Techniques** | `packers.yar` | 4 | UPX，MPRESS，Themida，通用 PE 异常 |
| **Techniques** | `shellcode.yar` | 4 | NOP sleds，GetPC，XOR 编码器，Metasploit 模式 |
| **Techniques** | `powershell.yar` | 4 | 编码命令，下载载体，AMSI 绕过，凭证窃取 |
| **Techniques** | `persistence.yar` | 4 | 注册表 Run 键，计划任务，WMI，服务 |
| **File Types** | `executables.yar` | 4 | 反调试，进程注入，可疑导入，ELF rootkit |
| **File Types** | `documents.yar` | 3 | VBA 宏，启用宏的 OOXML，PDF JavaScript |
| **File Types** | `scripts.yar` | 3 | 混淆的 JS，VBScript 释放器，Batch 恶意软件 |
| **Indicators** | `suspicious_strings.yar` | 3 | Tor C2，反分析，凭证访问 |
| **Indicators** | `crypto_indicators.yar` | 3 | 比特币/门罗币钱包，挖矿配置 |
| **Indicators** | `data_theft.yar` | 4 | FTP 外发，DNS 隧道，剪贴板窃取，电子邮件收集 |
| **总计** | | **53** | |
## 规则编写指南
### YARA 规则剖析
```
rule RuleName : tag1 tag2 {
meta:
author = "Edward Marez"
description = "What this rule detects"
severity = "critical" // critical/high/medium/low
date = "2026-03-31"
mitre_attack = "T1486 - Data Encrypted for Impact"
reference = "https://attack.mitre.org/techniques/T1486/"
strings:
// Text strings — case-insensitive, wide, or fullword
$s1 = "malicious string" nocase
$s2 = "DLL injection" nocase wide
// Hex strings — with wildcards
$h1 = { 4D 5A 90 00 ?? ?? 00 00 } // MZ header with wildcards
$h2 = { DE AD BE EF (01 | 02 | 03) } // Alternation
// Regex strings
$r1 = /\b[0-9a-f]{32}\b/ // MD5 hash pattern
condition:
// Show your knowledge here — not just "any of them"
any of ($s*) and $h1 at 0 and filesize < 5MB
}
```
### 编写有效的条件
**差（过于宽泛）:**
```
condition:
any of them // Matches if ANY one string appears — likely false positives
```
**好（具体明确）:**
```
condition:
// Require the PE header + at least 2 network strings + 1 injection API
uint16(0) == 0x5A4D and
2 of ($net*) and
any of ($inject*)
```
**更好（带有上下文）:**
```
condition:
// Only match if file is small (typical for shellcode) AND uses GetPC technique
filesize < 10KB and
(any of ($getpc*) or $nop_sled) and
#shellcode_str > 2
```
### 字符串修饰符参考
| 修饰符 | 作用 | 示例 |
|---|---|---|
| `nocase` | 不区分大小写匹配 | `"powershell" nocase` |
| `wide` | 匹配 UTF-16LE（Windows 字符串） | `"malware" wide` |
| `ascii` | 匹配 ASCII（默认） | `"test" ascii` |
| `fullword` | 仅匹配完整单词 | `"cmd" fullword` |
| `wide ascii` | 同时匹配两种编码 | `"evil" wide ascii` |
### Hex 通配符
```
{ 4D 5A } // Exact bytes
{ 4D ?? 5A } // One wildcard byte
{ 4D ?A 5A } // Low nibble wildcard
{ 4D A? 5A } // High nibble wildcard
{ (4D|5A) 90 00 } // Alternation
{ 4D [3-5] 5A } // Jump: 3 to 5 bytes between
```
## 检测覆盖范围
### 恶意软件家族
- **勒索软件:** WannaCry, Ryuk, LockBit, 通用加密行为
- **RAT:** AsyncRAT, njRAT (Bladabindi), 通用后门功能
- **挖矿程序:** XMRig, 通用 Stratum 挖矿程序, 浏览器加密劫持程序
- **Web Shell:** China Chopper, 通用 PHP/ASPX/JSP shell
### 技术 (MITRE ATT&CK)
| 技术 | ID | 覆盖模块 |
|---|---|---|
| 数据加密影响 | T1486 | ransomware.yar |
| 抑制系统恢复 | T1490 | ransomware.yar |
| 远程访问软件 | T1219 | trojans.yar |
| 进程注入 | T1055 | executables.yar |
| PowerShell | T1059.001 | powershell.yar |
| 资源劫持 | T1496 | cryptominers.yar |
| 服务器软件组件: Web Shell | T1505.003 | webshells.yar |
| 软件加壳 | T1027.002 | packers.yar |
| 启动/登录自动启动执行 | T1547 | persistence.yar |
| 计划任务/作业 | T1053 | persistence.yar |
| WMI 事件订阅 | T1546.003 | persistence.yar |
| AMSI 绕过 | T1562.001 | powershell.yar |
| 操作系统凭证转储 | T1003 | powershell.yar |
| 替代协议外带传输 | T1048 | data_theft.yar |
| 剪贴板数据 | T1115 | data_theft.yar |
| 调试器规避 | T1622 | executables.yar |
## 恶意软件分析概念
### 失陷指标
失陷指标 是表明系统已被入侵的工件。它们有以下几种形式：
- **基于哈希:** 已知恶意文件的 MD5/SHA-256（脆弱——会随着编译而改变）
- **基于网络:** C2 IP 地址、域名、URL 模式
- **基于主机:** 注册表键值、文件路径、互斥体名称、进程名
- **基于行为:** API 调用序列、字符串模式、字节签名（YARA 的目标）
### 静态与行为分析
| 分析类型 | 方式 | 优点 | 缺点 |
|---|---|---|---|
| **静态** | 在不执行的情况下检查文件（strings，反汇编，YARA） | 安全，快速，不需要沙箱环境 | 会被良好的混淆击败 |
| **动态/行为** | 在沙箱中运行，观察行为 | 能捕获混淆的恶意软件 | 沙箱可能会被检测/规避 |
| **混合** | 结合静态和动态 | 最佳覆盖范围 | 最消耗资源 |
YARA 支持大规模的**静态**分析——单条规则每小时可以扫描数百万个文件。
### 文件熵
香农熵用于测量数据中的随机性。这对于恶意软件分析至关重要：
- **< 4.0:** 纯文本，源代码
- **4.0–6.5:** 正常编译的可执行文件
- **> 7.0:** 加密数据，压缩段，或**加壳的恶意软件**
加壳程序会压缩原始可执行文件，并在前面附加一个在运行时解压的存根。
这使得加壳的节区在静态分析中呈现为高熵数据块——这是一个强烈表明需要进一步调查的指标。
### 加壳与混淆
恶意软件作者使用加壳程序来规避基于签名的检测：
- **UPX** (最常见): 开源加壳器，可通过节区名称 `UPX0`/`UPX1` 检测
- **Themida/WinLicense**: 带有基于 VM 混淆的商业保护器
- **自定义加壳器**: 专门为恶意软件编写的加壳器，没有签名
检测: YARA 规则可以通过魔术字节检测 UPX。高熵的 PE 节区结合极少的导入表条目通常表明是自定义加壳。
## 示例文件
`sample_files/` 目录包含了一个用于生成**合成**测试文件的生成器。
这些不是功能性的恶意软件——它们包含嵌入在噪声数据中的指标字符串，仅用于测试 YARA 规则的准确性。
```
# 生成测试样本
python sample_files/generate_samples.py
# 扫描它们以验证检测
python -m yaraforge scan --target sample_files/generated/ --recursive
```
## 运行测试
```
# 运行所有测试
python -m pytest tests/ -v
# 在覆盖率下运行
python -m pytest tests/ --cov=yaraforge --cov-report=html
# 运行特定测试模块
python -m pytest tests/test_matcher.py -v
```
## 许可证
MIT 许可证 — 见 [LICENSE](LICENSE)。
## 作者
**Edward Marez** | 网络安全学生，数字取证分析
GitHub: [@marez8505](https://github.com/marez8505)
标签：APT防御, DNS 反向解析, EDR, Homebrew安装, HTML报告, IOC检测, IP 地址批量处理, JSON报告, Python安全库, YARA, YARAForge, 云计算, 云资产可视化, 入侵指标, 勒索软件检测, 多模态安全, 安全应急响应, 开源安全工具, 恶意软件扫描器, 搜索语句（dork）, 文件扫描, 无本地依赖, 标记器, 模式匹配, 端点检测与响应, 纯Python, 网络信息收集, 网络安全, 脆弱性评估, 脱壳工具, 自动化资产收集, 规则引擎, 解析器, 评估器, 逆向工具, 逆向工程平台, 隐私保护