r3dzyoud/M4CR0SC0PE

## 概述 M4CR0SC0PE 是一个完全静态的分析 pipeline，用于检测和分析 Microsoft Office 文档中的恶意 VBA 宏。在任何阶段都不执行代码——所有分析均通过静态检查、结构化证据提取以及基于 LLM 的语义推理来完成，从而生成可解释的恶意软件报告。 ## Pipeline — 8 个阶段 ``` Office Document │ ▼ ┌─────────────────────────────────────────────┐ │ 1 · Validation & Hashing │ File type (magic bytes) · SHA-256 · MD5 ├─────────────────────────────────────────────┤ │ 2 · Static Macro Extraction │ oletools · OLE & OOXML · autoexec detection ├─────────────────────────────────────────────┤ │ 3 · Deobfuscation │ Chr() · Base64 · Hex · Dridex · String concat ├─────────────────────────────────────────────┤ │ 4 · Deep Static Analysis │ Behavioral & technical indicators ├─────────────────────────────────────────────┤ │ 5 · Evidence Builder │ Structured JSON · 3 epistemic tiers ├─────────────────────────────────────────────┤ │ 6 · LLM Semantic Analysis │ Verdict · Confidence · IOCs · MITRE proposals ├─────────────────────────────────────────────┤ │ 7 · MITRE ATT&CK Verification │ Evidence grounding · Hallucination detection ├─────────────────────────────────────────────┤ │ 8 · Reverse Engineering │ Call graph · Execution flow reconstruction └─────────────────────────────────────────────┘ │ ▼ Analysis Report ``` ## 截图 ### Dashboard  ### 分析  ### 报告  ### Assistant  ## 评估结果 | 模型 | 准确率 (Accuracy) | 精确率 (Precision) | 召回率 (Recall) | F1-Score | TP | TN | FP | FN | |-------|----------|-----------|--------|----------|----|----|----|----| | **GPT-4.1** | **75.6%** | 0.733 | **1.000** | **0.846** | 200 | 26 | 73 | 0 | | GPT-4o | 66.4% | 0.664 | 1.000 | 0.798 | 198 | 0 | 100 | 0 | | Claude Haiku | 75.5% | 0.710 | 1.000 | 0.831 | 147 | 38 | **60** | 0 | **所有模型均达到了完美的召回率 (1.000) —— 没有漏报任何恶意文件。** ### MITRE ATT&CK 幻觉率 | 模型 | 提出的技术数 | 已验证 | 已拒绝 | 幻觉率 | |-------|---------------------|----------|----------|--------------------| | GPT-4.1 | 759 | 654 | 105 | **13.8%** | | GPT-4o | 421 | 160 | 261 | 62.0% | | Claude Haiku | 1,475 | 795 | 680 | 46.1% | ## Dashboard 可通过 `http://localhost:5000` 的 Web 界面访问 4 个屏幕： | 屏幕 | 描述 | |--------|-------------| | **Dashboard** | KPI · 模型性能 · MITRE 技术图表 · 提交历史 | | **Analyze** | 上传文件 · 实时 8 阶段 pipeline · 实时结果预览 | | **Report** | 完整的结构化报告 · MITRE 表格 · IOC · 缓解措施 · PDF 导出 | | **Assistant** | 由 GPT-4.1 驱动 · 项目范围内的问答 · 感知报告的上下文 | ## 设置 ### 前置条件 - Python 3.10+ - pip - Azure OpenAI API key (GPT-4.1) - AgentRouter API key (Claude Haiku — 可选) ### 安装 ``` # 1. Clone the repository git clone https://github.com/r3dzyoud/M4CR0SC0PE.git cd M4CR0SC0PE # 2. Install dependencies pip install -r requirements.txt # 3. 配置环境 cp .env.example .env # 编辑 .env 并添加你的 API keys # 4. 运行 Dashboard python3 dashboard/app.py ``` 在浏览器中打开 `http://localhost:5000`。 ### 环境变量 ``` AZURE_OPENAI_API_KEY=your_key_here AZURE_OPENAI_BASE_URL=your_endpoint_here AGENTROUTER_API_KEY=your_key_here AGENTROUTER_BASE_URL=your_endpoint_here AGENTROUTER_MODEL_HAIKU=your_model_identifier_here ``` ## 支持的文件类型 | 格式 | 扩展名 | 描述 | |--------|-----------|-------------| | Word 宏 | `.docm` `.doc` | 包含 VBA 的 Word 文档 | | Excel 宏 | `.xlsm` `.xls` `.xlam` | 包含 VBA 的 Excel 工作簿 | | PowerPoint 宏 | `.pptm` | 包含 VBA 的 PowerPoint | | 模板宏 | `.dotm` | Word 宏模板 | | VBA 项目 | `.vba` | 独立的 VBA 项目 | ## 项目结构 ``` M4CR0SC0PE/ ├── macro_analyzer/ │ ├── stages/ │ │ ├── validation.py # Stage 1 — File type & hashing │ │ ├── extraction.py # Stage 2 — VBA extraction │ │ ├── deobfuscation.py # Stage 3 — Deobfuscation │ │ ├── analysis.py # Stage 4 — Static analysis │ │ ├── evidence_builder.py # Stage 5 — Evidence packaging │ │ ├── llm_reasoning.py # Stage 6 — LLM reasoning │ │ ├── mitre_verifier.py # Stage 7 — MITRE verification │ │ └── re_layer.py # Stage 8 — Reverse engineering │ ├── controller.py # Pipeline orchestration │ ├── database.py # SQLite persistence │ └── data_models.py # Shared data models ├── dashboard/ │ ├── app.py # Flask API + job runner │ └── static/ │ └── index.html # Single-page frontend ├── config/ │ └── vba_mitre_reference.json ├── dataset/ │ └── evaluation/ # Test/dev splits (CSV) ├── outputs/ │ └── evaluation/ # Evaluation results (JSON + CSV) ├── docs/ │ └── screenshots/ # Dashboard screenshots ├── .env.example ├── requirements.txt └── README.md ``` ## 主要贡献 - **基于证据的提示** —— 结构化的 JSON 证据包相比于原始 VBA 代码提示，能有效减少 LLM 幻觉 - **MITRE 验证阶段** —— 全新的基础层，将 LLM 提出的 ATT&CK 技术与静态证据进行交叉验证，从而产生可量化的幻觉率 - **多模型评估** —— 使用带有真实标签的 300 个真实宏恶意软件样本，对 GPT-4.1、GPT-4o 和 Claude Haiku 进行了系统性比较 ## 数据集 评估数据集来源于 **IEEE DataPort MSOffice VBA 宏分类数据集**。本仓库不会重新分发原始的恶意软件样本。请参阅 [IEEE DataPort MSOffice VBA 宏分类数据集](https://ieee-dataport.org/documents/msoffice-vba-macros-classified-dataset) 以获取样本访问权限。 SHA-256 哈希值和拆分清单可在 `dataset/subset_manifest.csv` 和 `dataset/evaluation/` 中找到。 ## 文档 完整的技术文档可在 [Wiki](https://github.com/r3dzyoud/M4CR0SC0PE/wiki) 中查看，涵盖： - 系统架构与数据流 - 逐阶段的实现细节 - LLM 集成与推理层 - MITRE 验证方法论 - Dashboard 与前端指南 - 可扩展性与自定义

标签：Clair, DAST, DLL 劫持, DNS 反向解析, Python, VBA宏检测, 云安全监控, 大语言模型, 威胁情报, 开发者工具, 恶意软件分析, 搜索语句（dork）, 无后门, 逆向工具, 静态分析