saadullahmughal/malware-explainer

# 恶意软件解释器 大多数杀毒软件在标记文件时会使用晦涩的家族名称，这对非技术用户来说几乎毫无意义——说实话，对许多计算机科学学生和开发人员来说也差不多。**Malware Explainer** 是一个研究驱动的个人项目，旨在解决这一问题：它分析 Windows PE 二进制文件，对其行为进行分类，并生成通俗易懂的英文解释，说明*为什么*该文件可疑以及*它可能会做什么*。 ## 工作原理 该流水线分 7 个阶段运行： ``` PE Binary (.exe) │ ▼ [1] Feature Extraction ← thrember / EMBER-compatible feature set │ ▼ [2] Binary Classification ← LightGBM — benign vs. non-benign (~90%+ ROC-AUC) │ (if flagged) ▼ [3] Behavior Classification ← LightGBM OvR multi-label (top-16 behavior labels) │ ransomware, trojan, spyware, downloader, rootkit, etc. ▼ [4] SHAP Explanation ← Which features drove each prediction? │ ▼ [5] PE Structure Inspection ← Extract context from binary for SHAP-focused features │ ▼ [6] LLM Report Generation ← Single consolidated Gemini API call → structured JSON │ ▼ [7] Markdown Report ← Saved to results/llm_explanations/{sha256}_{timestamp}/ ``` 其核心贡献在于**可解释性层**——使用 SHAP 将 LLM 的解释建立在实际的模型证据之上，而不是生成泛泛的恶意软件描述。 ## 输出示例 请参阅 [`results/llm_explanations/`](./results/llm_explanations/) 以查看由流水线生成的真实报告。 以下是对一个被标记的可执行文件分析的片段： ## 数据集与模型 - **数据集：** [EMBER2024](https://github.com/FutureComputing4AI/EMBER2024) — Joyce 等人，*Proceedings of the 31st ACM SIGKDD Conference on Knowledge Discovery and Data Mining*, 2025 - **二分类器：** LightGBM — 良性与非良性 - **行为分类器：** LightGBM OvR，排名前 16 的行为标签（勒索软件、木马、间谍软件、rootkit、下载器等） - **可解释性：** SHAP (SHapley Additive exPlanations) - **报告生成：** Google Gemini API（默认为 `gemini-3-pro-preview`） ## 快速入门 ### 1. 设置你的 API 密钥 代码仓库中包含一个 `.env.example` 文件。复制它并填入你的密钥： ``` cp analysis_pipeline/.env.example analysis_pipeline/.env ``` 然后编辑 `.env`： ``` GEMINI_API_KEY=your_key_here ``` ### 2. 安装依赖项 ``` pip install -r requirements.txt ``` ### 3. 运行流水线 ``` # 从 repository 根目录运行 python -m analysis_pipeline # 示例 python -m analysis_pipeline C:\path\to\sample.exe ``` ### 可选标志 | 标志 | 描述 | |------|-------------| | `--raw-features` | 在输出中包含原始特征向量 | | `--skip-llm` | 跳过 LLM 报告生成（仅运行步骤 1–5） | | `--llm-model ` | 覆盖默认的 Gemini 模型 | ### 输出 报告会自动保存至： ``` results/llm_explanations/{sha256}_{timestamp}/report.md ``` ## 当前局限性 这是一个早期阶段的 MVP（最小可行产品）。已知的局限性包括： - **仅限 CLI** — 尚无 GUI 或 Web 界面 - **仅限 EXE** — WinPE 格式，32/64 位；尚不支持 DLL 依赖项扫描 - **行为覆盖** — 由于训练期间的硬件限制，仅限于排名前 16 的标签集 - **LLM 忠实度** — 相对于真实特征上下文，真实度得分约为 60-70%；计划通过提示词工程进行改进 - **代码质量** — 研究级代码，正在积极清理中 ## 路线图 / 未来工作 - [ ] 在扫描主二进制文件的同时扫描导入的/依赖的 DLL - [ ] 将行为标签覆盖范围扩展到前 16 名之外 - [ ] 集成 / MoE（专家混合）方法 — 探索将 CatBoost 和 TabNet 作为互补模型（TabNet 的原生注意力机制可以减少对事后 SHAP 的依赖） - [ ] 集成 [Capa](https://github.com/mandiant/capa) 的结果作为 LLM 的额外上下文 - [ ] 通过提示词优化或 RAG 提升 LLM 的忠实度 - [ ] Web API / GUI ## 动机 这个项目最初是一项学术项目，后来演变成了一种真正的探索欲。我想了解被标记的二进制文件里到底有什么——而不仅仅是它的家族名称。像 Capa 和 VirusTotal 沙箱这样的工具已经存在，但该项目旨在填补的空白是为**非技术用户提供可解释性**，且这种解释建立在模型证据而非基于规则的签名之上。 ## 致谢 本项目使用了由 Joyce 等人在 *EMBER2024 - A Benchmark Dataset for Holistic Evaluation of Malware Classifiers* (KDD 2025) 中提出的 [EMBER2024](https://github.com/FutureComputing4AI/EMBER2024) 数据集。 ## 免责声明 本工具仅供教育和研究目的。请始终在隔离环境中分析可疑文件。

标签：Apex, DAST, DLL 劫持, DNS 反向解析, EMBER数据集, Gemini, LightGBM, LLM, PE文件分析, Rootkit, SHAP, Unmanaged PE, XAI, Zeek, 二进制分析, 云安全运维, 分类算法, 勒索软件, 可解释人工智能, 多标签分类, 大语言模型, 威胁情报, 开发者工具, 恶意软件分析, 木马检测, 机器学习, 特征提取, 网络安全, 自动化报告, 软件逆向工程, 逆向工具, 间谍软件, 隐私保护