noderaven/solid-macro

# solid-macro 这是一个演示现代 EDR 规避技术的 VBA 宏链，最初在 OSCP 学习期间编写，并在 v2 中进行了现代化改造，以适用于 Windows 11 24H2 / Microsoft Defender for Endpoint 时代。 ## 状态 - **v2** 是 `main` 分支的当前版本。采用模块化 VBA（9 个源文件加上生成的 `Payload.bas`）、Python 构建工具、ISO + LNK 投递包装器，并在每次 push 时进行 CI。 - **v1** 保留在 git 标签 `v1` 中。有关 v1 的详细说明和审查结果，请参阅 [docs/history.md](docs/history.md)（v1 文件存在许多导致其无法编译或运行的 bug —— 这次重写是一次彻底的重构，而不是简单的修补）。 ## 该链的作用 当组合生成的 `.docm` 文件在启用宏的 Word 中被打开时，会触发 `AutoOpen` 并执行包含八个阶段的 pipeline： ``` Phase 0 AMSI scans macro source pre-runtime; defeated by source obfuscation Phase 1 AutoOpen + ValidateEnvironment sandbox/uptime/domain keying Phase 2 Engine bootstrap DispCallFunc resolved; RW page allocated Phase 3 ResolveSyscalls map \KnownDlls\ntdll.dll; build SSN table Phase 4 Sensor blinding HWBP AMSI bypass + TEB ETW zero Phase 5 Payload decryption AES-256-CTR in pure VBA Phase 6 Injection dllhost-spoofed PPID + EarlyBird APC Phase 7 Schedule Cleanup Application.OnTime Now + 2s Phase 8 Cleanup (deferred) best-effort VBProject self-erase ``` 每种技术在 [docs/techniques.md](docs/techniques.md) 中都有详细介绍。这些阶段边界是刻意设计的：每个阶段都会返回一个状态，一旦失败就会干净地中止整个链，并且 `Debug.bas` 通过 `OutputDebugStringA` 提供逐阶段的遥测数据，以便于实验环境演练。 ## 仓库结构 ``` macro/ Strings.bas MkStr / MkAStr / HexToBytes (no flat sensitive literals) Structs.bas PE, NT, CONTEXT64, exception, Toolhelp32 types Engine.bas DispCallFunc shim, RWX hygiene, Call0..Call12 Aes.bas AES-256-CTR (mirror of payload/aes.py) Syscalls.bas HellsGate SSN extraction; SysCall0..SysCall12 Evasion.bas HWBP AMSI bypass via VEH; TEB.EtwTraceData zero Injection.bas PPID-spoofed CreateProcessW; NtAllocate/Write/Protect/Queue/Resume SolidMacro.bas AutoOpen, RunExploit, ValidateEnvironment, Cleanup Debug.bas DbgPrint / DbgAssert gated by DEBUG_ENABLED build/ assemble.py glues .bas files into a .docm-ready VBA project payload/ aes.py pure-Python AES-256-CTR (no third-party deps) build.py CLI: shellcode.bin -> macro/Payload.bas __init__.py delivery/ lnk/build_lnk.py pure-Python MS-SHLLINK builder iso/build_iso.py pycdlib-based ISO 9660 + Joliet builder xll/README.md future-work placeholder for the native twin tests/ pytest covering all Python tooling (43 tests) docs/ README files plus techniques / threat-model / delivery / development / history. .github/workflows/ci.yml pytest + assemble --check on push/PR ``` ## 快速开始 ``` # 1. 从你的 shellcode 生成 Payload.bas（使用 AES-256-CTR 加密） python payload/build.py path/to/shellcode.bin --out macro/Payload.bas # 2. 对组装好的 VBA 项目进行静态检查 python macro/build/assemble.py --check # 3. 组装模块集以备导入 Word VBA editor python macro/build/assemble.py # 已写入 macro/build/dist/Strings.bas # 已写入 macro/build/dist/Structs.bas # ...（共 10 个文件） # 4.（可选）打包以绕过 Mark-of-the-Web 进行投递 python delivery/lnk/build_lnk.py --target "data\\report.docm" --out report.lnk python delivery/iso/build_iso.py report.lnk data/report.docm --out report.iso ``` 如果您倾向于使用单次粘贴的工作流，而不是逐个模块导入，`assemble.py --flatten` 可以生成一个合并后的 `Module1.bas` 文件。 如果您的 PATH 中没有 `python`，请使用 `python3` —— 本仓库中的所有内容都针对 Python 3.10+ 版本。 ## 测试 Python 端通过 pytest 自动运行： ``` pip install pytest pycdlib==1.14.0 python -m pytest tests/ -v ``` 预期结果：43 个测试通过。 - `test_aes.py` 将 AES-256-CTR 实现锁定为 NIST FIPS 197（单块 KAT）和 NIST SP 800-38A Section F.5.5（4 块 CTR KAT）。其对应的 VBA 实现 (`Aes.bas`) 旨在实现逐字节镜像；如果 Word 端的解密产生错误输出，问题一定出在 `Aes.bas` 中，因为 Python 端已经严格遵循了标准。 - `test_assemble.py` 涵盖了静态检查规则：平衡的 `Sub/Function`、没有孤立的换行符，且没有直接明文的敏感 API 名称字面量。 - `test_build.py` 对 `payload/build.py` 的输出进行往返测试，通过正则表达式解析后再通过 AES 重新处理。 - `test_lnk.py` 和 `test_iso.py` 对生成的 LNK 和 ISO 文件进行字节级解析，以确认磁盘上的布局与 Windows 期望的一致。 GitHub Actions 会在每次 push 和 pull request 时在 Python 3.10 / 3.11 / 3.12 环境下运行此测试矩阵 —— 请参阅 [.github/workflows/ci.yml](.github/workflows/ci.yml)。 VBA 端需要在实验环境的 VM 中进行测试。有关手动工作流，请参阅 [docs/development.md](docs/development.md)：导入到 Word VBA 编辑器，执行 `Debug > Compile VBAProject`，然后通过 DebugView 结合 `winword.exe` 过滤器查看阶段遥测数据。 ## 范围与局限性 这是一个 OSEP 级别的研究产物。它使用的每一种技术都是公开记录过的 —— HellsGate 最早出现于 2020 年底，基于硬件断点的 AMSI 绕过自 2022 年以来已广为人知，通过 `UpdateProcThreadAttribute` 进行的 PPID 欺骗自 2011 年起就已公开。针对这些技术组合的检测规则已存在于公开发布的 YARA / Sigma / EDR 供应商特征库中。 [威胁模型](docs/threat-model.md) 准确列出了每种技术能够规避什么以及会被什么捕获。代表性总结如下： | 阶段 | 能够规避 | 会被捕获于 | |---|---|---| | HellsGate 间接 syscalls | NTDLL 用户态 hooks | MDE "syscall from non-image-backed memory" (~2024) | | HWBP AMSI 绕过 | 对 amsi.dll 的字节补丁扫描 | 来自 Office 的 VEH 安装 + DR0/DR7 变异 | | PPID 欺骗 | 正向进程树启发式检测 | 比较创建者 PID 与属性 PID 的内核回调 | | EarlyBird APC | 用户态 hook 竞争 | 跨进程写入 + QueueUserAPC 内核回调 | | ISO 包装的 LNK 投递 | 默认的 Mark-of-the-Web | `BlockDownloadsOfAllSamples` GPO, OOXMLFileSandboxAttachments | 如果您正在寻找可用于实战的顶级红队工具，那么这个项目并不适合您。但如果您正在准备 OSEP 考试，或者想了解现代 Office 宏规避链到底是如何构建的，这里的代码和设计理念文档都为您准备好了。 ## 构建 / 运行要求 - Python 3.10+ - `pip install pytest pycdlib==1.14.0` 用于测试套件 - 带有 x64 Windows 11 24H2 + x64 Microsoft Office 2016+ 的实验 VM，用于手动 VBA 验证流程 在*核心*构建路径中没有第三方 Python 依赖项（`payload/aes.py` 完全使用标准库）。`pycdlib` 仅被 ISO 投递包装器使用；`pytest` 仅用于开发。 ## 文档 | 文件 | 用途 | |---|---| | [README.md](README.md) | 本文件 | | [CHANGELOG.md](CHANGELOG.md) | v1 -> v2 记录 | | [docs/techniques.md](docs/techniques.md) | 各阶段技术深入解析 | | [docs/threat-model.md](docs/threat-model.md) | 真实的检测特征分析 | | [docs/delivery.md](docs/delivery.md) | Motw 原理，ISO/LNK 设计逻辑 | | [docs/development.md](docs/development.md) | 构建、测试、实验流程 | | [docs/history.md](docs/history.md) | v1 审查结果，v2 详细说明 | ## 授权与使用 仅在获得明确授权的情况下，方可使用这些技术，例如：经过授权的渗透测试项目、CTF 竞赛、教育学习（例如 OSEP / PEN-300 课程作业）以及防御性安全研究。请勿在未拥有或未获得书面测试许可的系统上部署此工具。 ## 许可证 MIT。请参阅 [LICENSE](LICENSE)。 ## 作者 [noderaven](https://github.com/noderaven)。欢迎通过 PR 提交贡献 —— 根据仓库惯例，请保持内容仅使用 ASCII 字符（不要使用长破折号 / 弯引号 / emoji）；提交记录应可归因于单人。

标签：EDR绕过, VBA宏, 免杀技术, 安全测试, 安全规则引擎, 攻击性安全, 暴力破解检测, 漏洞利用链, 逆向工具, 高交互蜜罐