MalEmu

[](https://github.com/0xMohammedHassan/MalEmu/actions/workflows/build.yml) [](LICENSE) []() []() MalEmu 允许你通过一个单一的 GUI 指向可疑的 `.exe` 文件，查看其 PE 头和节区信息，然后在模拟的 Windows 环境中观察二进制文件的执行过程，而无需在宿主机上实际运行它。随着代码的运行，Hook 机制会解码每一个 API 调用，从内存中提取字符串，并提取出 URL / IP / 互斥体 / 文件路径，以便你可以将一份分类报告直接交给下一位分析师。

_{MalEmu GUI mid-emulation on a synthetic sample -- ATT&CK techniques (T1071.001, T1071.004, T1124, T1497.001, T1622), capa capabilities (delay-execution), and YARA matches all firing live in the side panels while the emulation log streams the decoded API trace.}

本代码库是最初 PolyTest 项目的分支与重命名版本，为了实现便携式构建、CI（持续集成）以及开放的路线图而进行了重构。它是 **Alpha 阶段软件**——请预期存在不完善之处。 ## 适用场景 MalEmu 是专为恶意软件分析工作流中的特定环节而构建的工具。提前了解它的用途（以及不适用的场景）可以节省时间： **当你想要做以下事情时，请使用它：** - 在隔离的虚拟机中对未知的 32 位 Windows PE 文件进行分类，并在一分钟内获得一份一页纸的报告（包含静态 PE 头信息 + IOC + ATT&CK 技术 + capa 能力 + YARA 命中）。 - 根据观察到的字符串、API 调用模式和解包后的内存快照来构建 YARA / capa 规则——模拟中途的 YARA 扫描每执行 200 步就会扫描一次客户机内存，因此仅在解包后存在的特征规则依然会被触发。 - 以交互方式研究针对沙箱的逃逸响应。反反模拟面板公开了 14 个可切换的逃逸机制（`IsDebuggerPresent`、`CheckRemoteDebugger`、`NtQueryInfoProcess`、`CPUID` Hypervisor 叶、`RDTSC` 合成时钟、`GetTickCount/64`、`GetSystemFirmwareTable`、沙箱用户名/计算机名欺骗、`Sleep` / `NtDelayExecution` 时间钳制、`NtSetInformationThread::ThreadHideFromDebugger`、`OutputDebugString` 仅日志记录），这样你就可以在不重新构建的情况下切换开关并重新运行。 - 将 ATT&CK Navigator JSON 层直接放入你团队现有的检测工程流水线中。 - 通过无头（headless）的 `malemu-cli.exe` 生成可重现的、带有退出码的 JSON 报告，用于 CI 门禁、SOC 自动化或批量分类脚本。 **当你想要做以下事情时，请不要使用它：** - 替代商业化的行为沙箱（如 Joe Sandbox / Cuckoo / VMRay / Hatching）。它们的目标范围、规模和威胁模型完全不同。 - 端到端地模拟任意的 64 位恶意软件——x64 模拟在附带的示例以及能够通过 CRT 初始化的 `/MD` MSVC PE 文件上是可行的，但还不能保证适用于你在野外看到的所有 x64 二进制文件。请参阅下文的[局限性](#limitations)。 - 分析 .NET / 托管 PE（仅支持检测，无 CLR 模拟）、MinGW / Clang 构建的 PE（未经测试）、驱动程序 / 内核模式二进制文件（超出范围）或 ARM64 二进制文件。 如果你的工作流属于上述第一类，MalEmu 在目前阶段确实非常有用。如果是第二类，那么它就是错误的工具——这不是工具质量的问题，而是应用范围的问题。 ## 状态 (v0.7.0-rc.1) | 区域 | 状态 | |---------------------------------------|----------------------------------------| | 32位 PE 静态分析 | 正常运行 | | 32位 Unicorn 模拟 | 正常运行 | | 64位 Unicorn 模拟 -- `/MD` CRT | 正常运行 (PR4 + PR6.x) | | 64位 Unicorn 模拟 -- `/MT` CRT | **可用于分析 (v0.6.0-rc.4)** -- Trampoline 参数安全门使得 `StaticCrtX64` 能够顺利通过 CRT 初始化并调用 200 多个用户 API；在 `main()` 返回后的进程拆卸阶段，CLI 可能会以 `STATUS_ACCESS_VIOLATION` 退出（`--report` JSON 会在此之前被刷新写入） | | Win32 API Hook 覆盖范围 | ~90 个函数 | | 字符串 / IOC 抓取 | 启发式算法 | | MITRE ATT&CK 自动映射 | 正常运行 (PR5，在 `attack_map.json` v15.1 中包含 59 项技术) | | Navigator 层导出 | 正常运行 (PR5) | | capa 风格能力检测 | **正常运行 (PR7.0 / v0.7.0-rc.1)** -- 从 Mandiant [capa-rules v9.4.0](https://github.com/mandiant/capa-rules/releases/tag/v9.4.0) 编译了 803 条规则（由于 MalEmu 的静态追踪可观察性限制，有 239 条上游规则因仅支持动态或被精简为空而被跳过） | | YARA 预模拟 + 模拟中扫描 | 正常运行 (PR6.1) | | 内置 YARA 内容 | 4 条规则的入门包（`MalEmu/data/yara/malemu_basic.yar`）；通过 `tools/fetch_yara_corpus.ps1` 按需拉取的可选 **19,063 条规则**社区语料库（包含 signature-base + yara-rules + bartblaze）至 `external/yara-corpus/` 目录（已添加至 gitignore，包含混合的上游许可证）；加载和端到端执行已完成 (PR6.x)；**目前尚无阳性对照组** | | 无头 CLI (`malemu-cli`) | 正常运行 (PR6.1) -- v0.6.0-rc.4 为可捕获的宿主机 Trampoline 崩溃添加了 `_set_se_translator` SEH 包装器（出于设计考量，`__fastfail` 仍然是不可捕获的） | | .NET / 托管 PE | 仅支持检测 -- 无 CLR 模拟 | | MinGW / Clang 构建的 PE | 未经测试 | | 真实加壳恶意软件样本 | 未经测试（仅包含合成的 XOR 解包器） | | Sigma 导出 | 计划中 (PR6.2) | | STIX 2.1 / MISP 导出 | 计划中 (PR6.3) | | Docker 镜像 | 计划中 (PR6.4) | 完整的计划请参阅 [ROADMAP.md](ROADMAP.md)，详尽的限制列表请参阅 [docs/cli.md](docs/cli.md#limitations-v060-rc4)。 ### 生产环境就绪度 这是一个**发布候选版本**，而不是正式的 v1.0 生产版本。具体来说： - 可以安全地**发布为 `v0.7.0-rc.1`，并带有清晰的“发布候选版”横幅**——测试套件全部通过（在 x64 Release 上为 236/236，其中有 7 个已记录的跳过项属于仅 x86 / TLS / C++ EH 范畴；在 x86 Release 上为 234/234，其中有 10 个已记录的跳过项属于仅 x64 测试），YARA 流水线已通过约 19,000 条社区规则验证，且文档对应用范围的描述非常客观诚实。 - v0.7.0-rc.1 是一个在 v0.6.0-rc.4 基础上**专注于 GUI 的 rc**：在繁重的 API 流量下，模拟日志路径不再阻塞 GUI 线程（以前在几百次 API 调用后经常出现的 `(Not Responding)` 标题栏现象已经消失），反汇编按钮现在可以再次处理由汇编按钮生成的连续十六进制格式 `B8 02 00 00 00`，侧边面板列表框（CAPA / YARA / ATT&CK）支持水平滚动，使得过长的能力描述文本得以完整阅读，暗色模式覆盖了 PE 信息 / 检测层 / 静态标签 / 编辑框 / 列表框 / 复选框文本，并且 ATT&CK 面板不再与检测层堆栈发生视觉重叠。引擎侧的功能与 v0.6.0-rc.4 相比没有变化。 - **目前尚不宜宣称为“适用于任何 `.exe`”。** 在 [`docs/cli.md`](docs/cli.md#limitations-v060-rc4) 中的“样本兼容性”表格列出了当前支持的 PE 类型（原生 MSVC `/MD` 和 `/MT` x64，MSVC `/MD` x86）以及不支持的类型（C++ 异常 / VCRUNTIME140 RTTI、TLS 回调、.NET、MinGW/Clang、真实加壳程序、驱动程序、ARM64）。 - 它**没有经过任何第三方安全审计、模糊测试或代码签名**，并且如果格式错误的 PE 导致 Trampoline 崩溃，宿主进程将处于受影响范围内。务必在隔离的分析硬件上运行——参阅 [`SECURITY.md`](SECURITY.md)。 ## 快速入门 前置条件： - Visual Studio 2022（Desktop C++ 工作负载）或等效的 Build Tools - CMake >= 3.21（随 VS 2022 附带） - vcpkg 检出（checkout），并在环境变量中设置了 `VCPKG_ROOT` ``` git clone https://github.com/0xMohammedHassan/MalEmu.git cd MalEmu # 一次性：引导 bootstrap vcpkg（如果您尚未拥有） git clone https://github.com/microsoft/vcpkg.git C:\vcpkg C:\vcpkg\bootstrap-vcpkg.bat $env:VCPKG_ROOT = "C:\vcpkg" # 配置并构建 32-bit Release 预设（一次性完成 CLI + GUI） cmake --preset windows-x86-release cmake --build --preset windows-x86-release # 启动 GUI .\build\windows-x86-release\bin\Release\MalEmu.exe # 或者对捆绑的 HelloLoop 示例运行 headless CLI .\build\windows-x86-release\bin\Release\malemu-cli.exe ` .\build\windows-x86-release\bin\Release\HelloLoop.exe ` --yara-rules .\build\windows-x86-release\bin\Release\data\yara ` --report report.json --pretty --quiet ``` 无头 CLI 使用相同的引擎，但没有 GUI，并提供用于 CI 门禁的确定性退出码。`malemu-cli --help` 列出了每个标志及其默认值和单行描述：

_{The headless malemu-cli.exe built-in help. Full argument reference, exit-code contract, and --report JSON schema live in docs/cli.md.}

其他三种构建路径——Visual Studio 中的“打开文件夹”、生成 `.sln` 文件以及 CI/无头模式——记录在 [docs/BUILDING.md](docs/BUILDING.md) 中。CLI 的完整参数参考、退出码以及 `--report` 架构存放在 [docs/cli.md](docs/cli.md) 中。 ## 包含功能一览 - **静态 PE 分析器** -- DOS / NT / 可选头、节区、导入表、导出表、安全标志（ASLR、DEP/NX、SafeSEH、CFG）、入口点健全性检查、加壳提示。 - **基于 Unicorn 的模拟器** -- 将 32 位或 64 位 PE 加载到合成的 Windows 进程中，模拟 `kernel32.dll` / `user32.dll` / `ws2_32.dll` 等，解析导入，应用重定位，并从入口点开始运行。 - **API Hook 层** -- 拦截约 90 个 Win32 函数；参数和返回值被解码为人类可读的行（文件名、注册表路径、URL、分配大小等）。 - **多层字符串 / IOC 抓取器** -- 初始内存扫描、运行时 Hook 解码、执行期间的周期性扫描、堆栈抓取和堆分配跟踪。可捕获 URL、IP、域名、文件路径、注册表键、互斥体名称以及一些加密钱包模式。 - **MITRE ATT&CK 自动映射** -- 声明式的 `attack_map.json`（根据 MITRE ATT&CK v15.1 进行版本控制）将 API 调用、IOC 类型和注册表写入模式映射到 ATT&CK 技术。**开箱即包含 59 项技术**，每项技术都有一个或多个多指标触发器（api_call / api_sequence / ioc_kind / string_substring / registry_write）。完整的上游技术列表（637 项技术）也附带在 `external/mitre/techniques.csv` 中，供分析师参考。实时的“ATT&CK 技术”GUI 面板 + Navigator 层导出。详见 [docs/attack_mapping.md](docs/attack_mapping.md)。 - **capa 风格能力检测** -- 手写评估器（`MalEmu/src/engine/capa_detector.cpp`）遍历与 ATT&CK 检测器相同的 `EngineEvent` 流，并评估位于 `MalEmu/data/capa_rules.json` 的声明式规则包。该包包含 **803 条规则**，由 `tools/convert_capa_rules.py` 从固定的 [`capa-rules v9.4.0`](https://github.com/mandiant/capa-rules/releases/tag/v9.4.0)（提交 `2af9fbf`）离线编译而成；有 239 条上游规则被跳过，因为它们需要 MalEmu 实时追踪无法观察到的动态特性（177 条），或者在经过 MalEmu 的静态追踪投影后缩减为空（62 条）。每条触发的规则都带有上游规则的 ATT&CK + MBC 交叉引用，直接引入报告和 GUI 的“CAPA 能力”面板。通过 `--cap-fail-threshold` CLI 门禁。详见 [docs/capa_mapping.md](docs/capa_mapping.md)。 - **YARA 预模拟 + 模拟中扫描** -- 通过 vcpkg 编译引入的 libyara。预模拟阶段针对原始 PE 字节运行；模拟中途阶段每 200 个模拟步骤遍历一次 `uc_mem_regions`，以捕获仅在解包后存在的签名特征。代码库附带了一个 **4 条规则的入门包**，位于 `MalEmu/data/yara/malemu_basic.yar`（包含 PE MZ 健全性检查、MSVC Rich 头信号、PowerShell `-EncodedCommand` 命令行、HKCU Run 键持久化路径），二进制文件会自动从 `bin//data/yara/` 加载该包。如需更广泛的覆盖范围，请运行 `tools/fetch_yara_corpus.ps1` 以按需拉取可选的社区语料库至 `external/yara-corpus/` 目录（已添加至 gitignore）：包含 1,419 个文件和 19,063 条独立规则，源自 [Florian Roth 的 signature-base](https://github.com/Neo23x0/signature-base)（743 个文件，DRL 1.1）、[Yara-Rules 社区包](https://github.com/Yara-Rules/rules)（566 个文件，GPL-2.0）以及 [BartBlaze 的规则](https://github.com/bartblaze/Yara-rules)（110 个文件，MIT）。将 `--yara-rules` 指向语料库路径（或你自己的任何目录）以进行非入门级工作。实时的“YARA 匹配”GUI 面板 + 报告侧的 `yara_matches[]`。有关许可说明，请参阅 [docs/yara_integration.md](docs/yara_integration.md) 和 [docs/yara_corpus_coverage.md](docs/yara_corpus_coverage.md)。 - **无头 CLI (`malemu-cli.exe`)** -- 相同的引擎，没有 GUI。输出统一的 JSON 报告 + Navigator 层，带有用于 CI 门禁的确定性退出码。详见 [docs/cli.md](docs/cli.md)。 - **内置反汇编器 / 汇编器** -- 使用 Capstone 进行 `字节 -> 汇编`，使用 Keystone 进行 `汇编 -> 字节`。 - **实时 GUI** -- 用于反汇编、日志、IOC 列表、ATT&CK 和 YARA 面板的暗色主题 RichEdit 窗格，以及一个 GDI+ 调用流图；随着分析进行自动保存模拟日志。 关于每个面板和 Hook 类别的详细演示记录在 [docs/FEATURES.md](docs/FEATURES.md) 中（即最初的 PolyTest README，作为功能清单参考予以保留）。 ## 局限性 诚实的清单，并在每个 rc 版本中保持更新。详尽的按 PE 类型划分的表格位于 [`docs/cli.md`](docs/cli.md#limitations-v060-rc4) 中；本节重点指出分析师在实际操作中会遇到的问题。 **引擎 / 模拟：** - **64 位模拟尚不完善。** 内置的 `HelloLoop64.exe` 和 `InjectorSim64.exe` 可以端到端正常运行；许多现实世界中的 x64 PE 文件会卡在 CRT 初始化阶段（在 [ROADMAP.md](ROADMAP.md) 中作为第 4.4 项进行追踪）。v0.6.0-rc.4 的 Trampoline 参数安全门将 `/MT` 静态 CRT 样本（如 `StaticCrtX64.exe`）移出了“当前会崩溃”的行列，但尚未普及到所有的 x64 二进制文件。 - **协作式取消尚不完整。** 在模拟运行期间点击 **Stop**、**Detach PE** 或 **Clear All**，在某些代码路径下将无法在 5 秒内响应停止信号，并会弹出 `MalEmu engine compromised` 对话框。此时该线程将被放弃，在加载下一个样本之前必须重新启动进程。此问题在 PR3.5 / PR4 的跟进计划中追踪。 - **没有真实的恶意软件语料库运行记录。** 样本套件是合成的（`HelloLoop`、`InjectorSim`、XOR 解包器夹具）。YARA 流水线已针对约 19,000 条公开规则进行了验证，但尚未对确认的恶意软件建立阳性对照。 - **没有第三方安全审计、模糊测试或代码签名。** 格式错误的 PE 导致 Trampoline 崩溃仍然会使宿主进程处于受影响范围内。务必在支持快照还原且网络隔离的虚拟机中运行。请参阅 [`SECURITY.md`](SECURITY.md)。 **GUI：** - **GUI 是纯手工打造的 Win32 v1。** 采用固定像素布局，尚未进行 `WC_TABCONTROL` 重构（根据 ROADMAP 5.5 推迟）。在缩放比例超过 150% 的 HiDPI 宿主机上，某些标签可能会换行并覆盖到相邻面板。 - **暗色模式涵盖了 RichEdit、列表框、静态标签、编辑框、主背景以及 AAP / Auto-Save / Dark-Mode 复选框文本。** 按下按钮（如 Open PE / Detach / Start Emulation 等）有意保留了系统主题——带有主题的 Win32 按钮会忽略 `WM_CTLCOLORBTN`，而对其进行所有者绘制（owner-draw）会引入焦点和悬停相关的 Bug。这也是 VS Code、Sublime Text 和大多数部分支持暗色的 Win32 应用所做出的相同妥协。 - **系统对话框保持系统主题。** `MessageBox` 弹窗、`GetOpenFileName` / `GetSaveFileName` 选择器以及调用流图窗口不遵循暗色模式开关。 - **暗色模式偏好设置在跨次启动时不会持久化。** 复选框始终默认为未选中状态。 - **组合框下拉过滤器**（`All / Network / File / ...`）即使在暗色模式下也可能显示浅色的关闭状态——Win32 组合框内部机制是公认的暗色模式痛点。 **覆盖范围：** - **.NET / 托管 PE** -- 仅支持检测，无 CLR 模拟。 - **MinGW / Clang 构建的 PE** -- 未经测试。 - **驱动程序 / 内核模式二进制文件** -- 超出范围。 - **ARM64 二进制文件** -- 不支持。 如果你遇到了未在此列表中的问题，请提交一个 Issue——我们宁愿诚实地扩充这个列表，也不愿让分析师在调查过程中自己去发现缺陷。 ## 文档导航 | 文件 | 涵盖内容 | |------|----------------| | [docs/BUILDING.md](docs/BUILDING.md) | 构建矩阵（CMake 预设、VS Open Folder、生成的 `.sln`、CI）、前置条件、故障排除 | | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | 高级组件图及 `MalEmu/src/` 中的结构说明 | | [docs/FEATURES.md](docs/FEATURES.md) | 当前功能的详细清单（原文来自旧版 README） | | [docs/attack_mapping.md](docs/attack_mapping.md) | `attack_map.json` 的工作原理——指标类型、去重规则、添加新技术 | | [docs/capa_mapping.md](docs/capa_mapping.md) | capa 规则如何从上游 YAML 转换为 MalEmu JSON（`tools/convert_capa_rules.py`）、JSON 架构、支持的特性和已知跳过项，以及触发的 capa 规则如何交叉引用 ATT&CK + MBC | | [docs/yara_integration.md](docs/yara_integration.md) | YARA 预模拟 + 模拟中扫描、GUI 面板、无头布线、位于 `MalEmu/data/yara/malemu_basic.yar` 的 4 条规则入门包，以及 `external/yara-corpus/` 下的可选按需社区语料库（通过 `tools/fetch_yara_corpus.ps1` 拉取） | | [docs/cli.md](docs/cli.md) | `malemu-cli.exe` 参数参考、退出码、`--report` 架构、CI 示例 | | [ROADMAP.md](ROADMAP.md) | 按版本和 PR 划分的计划，包含哈希、ATT&CK 映射、YARA、Sigma、STIX、MISP 和 CLI 的代码模型 | | [SECURITY.md](SECURITY.md) | 漏洞披露策略 + 恶意软件处理安全须知 | | [CONTRIBUTING.md](CONTRIBUTING.md) | 如何提交 PR | | [CHANGELOG.md](CHANGELOG.md) | 发行说明 | ## 安全须知 MalEmu 在 Unicorn 内部模拟代码，因此目标二进制文件的指令永远不会在你的 CPU 上原生执行。被 Hook 的 API 返回合理的模拟值，而不是去接触你的文件系统、网络或注册表。**然而**，MalEmu 仍处于 Alpha 阶段，宿主进程依然会将样本字节加载到内存中，并且 Win32 环境模拟绝不能替代经过加固的分析型虚拟机。 **在处理未知样本时，务必在专用的、网络隔离的分析硬件（或支持快照还原的虚拟机）上运行 MalEmu。** 详见 [SECURITY.md](SECURITY.md)。 ## 许可证 MalEmu 的源代码基于 [Apache-2.0](LICENSE) 许可证授权。 MalEmu 链接了 [Unicorn](https://www.unicorn-engine.org/) 和 [Keystone](https://www.keystone-engine.org/)，这两者均为 GPLv2 许可证。因此，分发的二进制文件受 GPLv2 义务的约束——有关组合分发的详细说明，请参阅 [NOTICE](NOTICE)。

标签：Bash脚本, C2检测, capa规则, Cloudflare, Conpot, DAST, GUI安全工具, Linux, MITRE ATT&CK, PE文件分析, PE模拟器, Unicorn引擎, Win32 API钩子, Windows安全, YARA匹配, 云安全监控, 云资产清单, 威胁情报, 开发者工具, 开源软件, 恶意软件分析, 恶意软件分析工具包, 无头CLI, 沙箱, 网络安全, 计算机应急响应, 运行时IOC提取, 逆向工程, 隐私保护, 静态分析