## 项目简介
这是一个**基于 Python 的静态分拣 pipeline**，可自动化恶意软件分析师对可疑文件执行的应急响应工作流。只需将文件放入 `samples/` 文件夹——该 pipeline 就会计算加密哈希值、编译并针对每个文件运行 YARA 规则、提取元数据，并在几秒钟内输出专业的 HTML 和 CSV 报告。
这复现了真实的 SOC/DFIR 分拣任务：**识别 → 哈希计算 → 扫描 → 记录 → 报告**。
## 演示
### Pipeline 运行
Pipeline scanning 3 files — 2 YARA hits detected, 1 clean
### HTML 分拣报告输出
Auto-generated HTML report with color-coded threat status, hashes, and YARA matches
## 项目结构
```
cyber-triage-pipeline/
│
├── pipeline.py ← Main automation script
├── banner.svg ← Project banner
│
├── rules/
│ └── basic.yar ← YARA detection rules
│
├── samples/
│ ├── sample1.txt ← Test: suspicious script keywords
│ ├── sample2.txt ← Test: ransomware indicators
│ └── sample3.txt ← Test: benign file (clean)
│
├── reports/
│ ├── report_*.html ← Auto-generated HTML reports
│ └── report_*.csv ← Auto-generated CSV reports
│
└── screenshots/ ← Project documentation images
```
## 工作原理
```
┌─────────────┐ ┌──────────────┐ ┌─────────────┐ ┌──────────────┐
│ Input Files│────▶│ Hash Engine │────▶│ YARA Scanner│────▶│ Report Gen │
│ samples/ │ │ MD5/SHA256 │ │ .yar rules │ │ HTML + CSV │
└─────────────┘ └──────────────┘ └─────────────┘ └──────────────┘
```
**逐步流程：**
1. **加载 YARA 规则** — `rules/` 中的所有 `.yar` 文件都会被编译成一个单一的规则集
2. **文件发现** — `samples/` 中的每个文件都会被加入分析队列
3. **哈希计算** — 为每个文件计算 MD5、SHA1 和 SHA256（确保完整性，并为 VirusTotal 查询做好准备）
4. **元数据提取** — 提取文件大小、创建时间、最后修改时间戳
5. **YARA 扫描** — 使用所有编译好的规则对每个文件进行扫描；记录匹配的规则名称
6. **报告生成** — 将带有时间戳的 HTML（适配浏览器查看）和 CSV（便于分析师使用）保存到 `reports/` 文件夹
## 包含的 YARA 规则
Detection rules written for two malware behavior categories
| 规则名称 | 检测内容 | 条件 |
|---|---|---|
| `Suspicious_Script` | cmd.exe, powershell, base64, wget 关键词 | 4 个字符串中匹配 2 个 |
| `Possible_Ransomware` | encrypt, bitcoin, ransom 关键词 | 3 个字符串中匹配 2 个 |
规则使用了 `nocase` 匹配和 **"2 of N" 条件**来减少误报——这与生产级 YARA 规则集中使用的逻辑相同。
## 设置与安装
### 环境要求
- Python 3.12（推荐使用——因为 3.14+ 暂未提供 yara-python wheel 包）
- Windows / Linux / macOS
### 快速开始
```
# 1. Clone 仓库
git clone https://github.com/YOUR_USERNAME/cyber-triage-pipeline.git
cd cyber-triage-pipeline
# 2. 使用 Python 3.12 创建虚拟环境
py -3.12 -m venv cyber_env
# 3. 激活它
# Windows:
cyber_env\Scripts\activate
# Linux/Mac:
source cyber_env/bin/activate
# 4. Install 依赖
pip install yara-python pandas requests
# 5. 运行 pipeline
python pipeline.py
```
### 添加你自己的样本
将任何可疑文件放入 `samples/` 文件夹，然后运行 `python pipeline.py`。报告将自动带上时间戳保存到 `reports/` 中。
## 输出示例
### 终端输出
```
==================================================
CYBERSECURITY AUTOMATION PIPELINE
==================================================
[*] Loading YARA rules...
[*] Scanning 3 file(s)...
-> sample1.txt
YARA HIT -> ['Suspicious_Script']
-> sample2.txt
YARA HIT -> ['Possible_Ransomware']
-> sample3.txt
Clean
[*] Generating reports...
[+] HTML report saved -> reports/report_20260625_160333.html
[+] CSV report saved -> reports/report_20260625_160333.csv
==================================================
DONE — 3 files processed
==================================================
```
### 报告列（CSV / HTML）
| 列名 | 描述 |
|---|---|
| `filename` | 被扫描文件的名称 |
| `size_bytes` | 文件大小（字节） |
| `md5` | 用于快速识别的 MD5 哈希值 |
| `sha1` | SHA1 哈希值 |
| `sha256` | SHA256 哈希值（可直接用于 VirusTotal 查询） |
| `created` | 文件创建时间戳 |
| `modified` | 最后修改时间戳 |
| `yara_matches` | 触发的 YARA 规则名称，或为 "None" |
## 环境与依赖
Verified working environment with yara-python 4.5.4
| 包名 | 版本 | 用途 |
|---|---|---|
| `yara-python` | 4.5.4 | YARA 规则编译与扫描 |
| `pandas` | 3.0.3 | 生成 CSV 报告 |
| `requests` | 2.34.2 | 预留用于未来的 VirusTotal API 富化查询 |
| `numpy` | 2.5.0 | Pandas 的依赖项 |
## 已验证的文件夹结构
Clean project layout: samples, rules, reports separated by concern
## 演示的核心概念
| 概念 | 实现方式 |
|---|---|
| **文件完整性** | 通过 `hashlib` 计算 MD5 / SHA1 / SHA256 — 与 DFIR 中的证据保管链哈希一致 |
| **检测工程** | 结合字符串模式和布尔条件的自定义 YARA 规则 |
| **静态分析** | 不执行代码 — 仅检查处于静止状态的文件内容 |
| **减少误报** | 使用 "2 of N" YARA 条件代替单字符串触发 |
| **自动化** | 单条命令即可端到端处理无限量文件 |
| **分析师报告** | 使用 HTML 供人工审查，CSV 用于数据处理 / 导入 SIEM |
## 扩展本项目
- **集成 VirusTotal** — 将 SHA256 哈希值提交给 VT API 进行信誉查询
- **添加更多 YARA 规则** — 为特定的恶意软件家族（Emotet、Cobalt Strike 等）添加规则
- **导出至 MISP** — 以兼容 MISP 的 JSON 格式输出 IOC
- **邮件告警** — 在发现 YARA 命中时通过邮件发送报告
- **递归扫描** — 自动扫描嵌套的子目录
## 面试谈论要点
- **静态分析**（本项目）和**动态分析**（沙箱/Cuckoo）之间的区别
- 为什么在 VirusTotal 查询中更倾向于使用 **SHA256** 而不是 MD5（抗碰撞性）
- **"2 of N" YARA 条件**如何在生产环境中减少误报
- 为什么带有**时间戳的报告**对于 DFIR 调查中的证据保管链至关重要
## 相关项目
- **项目 1** — 针对恶意软件家族的 YARA 规则包
- **项目 2** — 来自沙箱的恶意软件行为报告
- **项目 3** — IOC 提取与威胁情报映射器
- **项目 4** — 内存取证恶意软件追踪
## 许可证
MIT 许可证 — 可免费使用、修改和分发。
专为恶意软件分析 · DFIR · 威胁情报 · SOC 自动化岗位构建