kryptbakar/Malware-Analysis-Triage-Pipeline

# 🧪 恶意软件分析分诊流水线 **自动化、可解释的 Windows-PE 分诊。** 输入一个可疑文件；返回一份分析师级别的判定结果，该结果结合了静态分析、ML 分类器、MITRE ATT&CK 映射和 IOC 提取 —— 并提供 **SHAP 解释，使得每一个判定都有理可依**，而非主观断言。 它将一级分析师需要耗时一小时完成的工作，压缩成了一条可重复的、耗时仅几秒的流水线。 ``` ┌─────────────── SAFE (no execution) ───────────────┐ File ──▶ Ingest ──▶ Static ──▶ Features ──▶ ML + SHAP ──┐ hash/type PE parse EMBER-style verdict + │ dedupe entropy vectors reasons │ quarantine imports/ ▼ strings/YARA ATT&CK mapping │ ┌──── ISOLATED LAB (execution, v2) ────┐ ▼ File ──▶ CAPEv2 ──▶ behavior + netflow ─────────┴─▶ IOC extract + enrich ──▶ Report (fake-internet sink, Suricata) (VT/AbuseIPDB, STIX 2.1) HTML/PDF/JSON + UI ``` 开发初衷：SOC 经常被海量可疑文件淹没，人工分诊缓慢且不一致，而商业工具（VirusTotal、Joe Sandbox）又是不透明的黑盒。本项目是一个透明、自托管的分诊引擎，**ML 决策结果是可以被解释的**。 ## 目前已实现功能 | 阶段 | 状态 | 备注 | |---|---|---| | **接收** | ✅ | SHA-256/MD5/imphash、magic-byte 类型识别、SQLite 去重、隔离存储 | | **静态分析** | ✅ | pefile 解析、逐节区 Shannon 熵、import→capability 提示、字符串/IOC 提取、**YARA**、capa 封装 | | **ML + SHAP** | ✅ | 基于 1049 维 EMBER 风格向量的 LightGBM 检测器 + 家族分类器；SHAP `TreeExplainer` 提供每次判定的影响因子 | | **ATT&CK** | ✅ | capabilities/behaviours → techniques → **Navigator layer JSON** (热力图) | | **IOC + STIX** | ✅ | 提取 → (可选) 丰富 (VT/MalwareBazaar/AbuseIPDB) → **STIX 2.1** bundle | | **报告生成** | ✅ | Jinja2 → HTML + JSON (+ 通过 WeasyPrint 生成 PDF)、Navigator layer、STIX | | **API / UI** | ✅ | FastAPI 服务 + 拖拽式 dashboard；可选 Celery/Redis 异步处理 | | **动态分析** | 🧪 v2 | CAPEv2 提交 + 报告解析器；**默认关闭，仅在隔离实验环境中运行** | 29 个通过的测试 · 当缺少可选的原生工具 (yara/capa/weasyprint/ember) 时能够优雅降级。 ## 快速开始 ``` pip install -e . # core deps (pefile, lightgbm, shap, fastapi…) # 可复现的安装替代方案：pip install -r requirements.lock -e . --no-deps # 可选：pip install -e ".[full]" # yara-python, capa, weasyprint, celery… python -m ml.train # train the bundled DEMO model (~4s, no dataset needed) # 生成一个安全、无危害的测试样本 python tests/make_fixture_pe.py samples/suspicious.exe --malicious # 对其进行分诊 python cli.py analyze samples/suspicious.exe --out out ``` ``` 🔴 MALICIOUS (score 100.0/100) file : suspicious.exe [PE32 executable (Windows)] sha256 : 947e3dfed19cefe86b59b190b5f6f89cc42b9a0bf676c395f8d6f9cd4011345e ml : 93.1% malicious family=downloader (91%) tags : downloader, packed, persistence-registry, process-injection why : ▲ +1.29 2 imported API(s) enabling 'dynamic api resolution' ▲ +0.20 process-injection imports present att&ck : T1106, T1027, T1055, T1105, T1112, T1134, T1547.001 iocs : 8 extracted (domain, imphash, ip, md5, mutex, registry, sha256, url) 📁 artifacts written to out/: json / html / navigator.json / stix.json ``` ### Web 仪表板 ### 编程方式调用 ``` from pipeline import triage from report import write_all report = triage("sample.exe") # TriageReport dataclass print(report.verdict, report.score, report.ml.family) write_all(report, "out/") # json + html + navigator + stix (+pdf) ``` ## ML 子系统（核心差异化优势） | 方面 | 选择 | |---|---| | **算法** | LightGBM GBDT — 二分类 (malicious/benign) + 多分类 (family) | | **特征** | Byte & byte-entropy 直方图、header/section 统计数据、**命名的 per-capability API 计数** (可解释)、哈希化的 imports/DLLs/exports、字符串统计数据、数据目录 → 1049 维向量。详见 `ml/features/pe_features.py`。 | | **生产数据** | **EMBER 2018** (1.1M PEs, 2381 features)，通过 `ml/train_ember.py` 处理；当安装了 `ember` 包时，会自动切换至 EMBER 的 `PEFeatureExtractor` | | **评估** | ROC-AUC、PR-AUC、**FPR @ 95% TPR** (SOC 关注误报率)、混淆矩阵、family macro-F1 | | **可解释性** | SHAP `TreeExplainer` → 针对每次判定的正负影响因子 + 人类可读叙述 ("flagged: injection imports + high .text entropy") | ## 仓库结构 ``` ingest/ hashing, filetype, dedupe, quarantine static/ PE parse, entropy, strings, YARA, capa, capability inference dynamic/ CAPEv2 submit + report parser (v2, isolated lab only) ml/ features/ · train · predict · explain(SHAP) · eval · train_ember · model_card attack/ technique registry, behaviour→technique mapping, Navigator layer iocs/ extract, enrich (VT/AbuseIPDB/MalwareBazaar), STIX 2.1 export report/ Jinja2 templates → html/pdf/json api/ FastAPI service + dashboard + Celery scaffold rules/ YARA rules (demo; drop signature-base here for real coverage) lab/ Vagrantfile + isolation docs + SAFE_SAMPLES.md core/ shared config, data models, logging, utils tests/ pytest suite + safe PE fixture generator ``` ## 安全与伦理 ⚠️ 只有 `dynamic/` 阶段会执行样本，并且只在**隔离实验环境** (`lab/`) 中运行：仅主机网络、快照、伪互联网接收器 (INetSim/FakeNet-NG)、无共享/自动运行文件夹。**除非设置了 `CAPE_URL`，否则引爆 (Detonation) 是关闭的**。 其他所有阶段绝不会运行样本。 `samples/` 和 `quarantine/` 已被 git 忽略 —— **绝不提交任何活体恶意软件**。样本仅用于防御性研究和教育，且来源于公认的研究仓库。请从 EICAR 和生成的无活性测试夹具 (fixtures) 开始。参见 [`lab/SAFE_SAMPLES.md`](lab/SAFE_SAMPLES.md)。 ## 路线图 - [x] **阶段 1** — 静态分析核心 → JSON - [x] **阶段 2** — EMBER 风格的 LightGBM + SHAP + 评估 + 模型卡片 - [x] **阶段 3** — ATT&CK Navigator layer、STIX 导出、信息丰富 - [x] **阶段 4** — HTML/JSON 报告、FastAPI + dashboard - [ ] **阶段 5** — CAPE 实验室引爆、behaviour→ATT&CK、样本分析报告 - [ ] 拓展目标 — 自动脱壳、Volatility3 内存取证、YARA 自动生成、对抗性 ML 鲁棒性 ## 技术栈 Python · pefile/lief · yara-python · capa · CAPEv2 · INetSim/FakeNet-NG · Suricata · LightGBM · scikit-learn · SHAP · EMBER/BODMAS · stix2 · mitreattack-python · FastAPI · Celery/Redis · Jinja2/WeasyPrint · Vagrant/VirtualBox. ## 许可证 MIT — 详见 [`LICENSE`](LICENSE)。仅供研究和防御性使用。

标签：Apex, DAST, Metaprompt, 云安全监控, 可解释AI, 威胁情报, 开发者工具, 恶意软件分析, 搜索引擎查询, 机器学习, 自动化分诊, 逆向工具, 静态分析