entropykit/entropia

## 不到 30 行代码实现一个完整的 BOF ``` use bof; use_c "stdlib/win32/toolhelp.h"; fn go(args: char*, len: int) -> void { var snap: u64 = (u64)Kernel32.CreateToolhelp32Snapshot(TH32CS_SNAPPROCESS, 0); if snap == 0xFFFFFFFFFFFFFFFF { ret; } var pe: PROCESSENTRY32; pe.dwSize = (u32)sizeof(PROCESSENTRY32); var ok: int = Kernel32.Process32First((void*)snap, &pe); while ok != 0 { BeaconPrintf(CALLBACK_OUTPUT, str.format("[+] {d} {s}\n", (int)pe.th32ProcessID, (char*)pe.szExeFile)); ok = Kernel32.Process32Next((void*)snap, &pe); } Kernel32.CloseHandle((void*)snap); ret; } ``` 这是一个完整的 `ps` BOF。`use_c` 行直接从 Windows SDK 头文件中提取 `PROCESSENTRY32` 结构体和 `TH32CS_SNAPPROCESS` 常量，因此你可以通过名称来编写快照类型，而不是使用原始的 `0x2`，并且结构体布局与 Microsoft ABI 逐字节匹配。无需手动构建 IAT，也无需自行应用重定位。`Kernel32.X(...)` 调用会下沉为间接调用，通过运行时在用户代码运行前填充的槽位进行。 ## 快速开始 ``` git clone https://github.com/entropykit/entropia.git cd entropia # 构建 workspace（3 个二进制文件：entc、bof-runner、entc-debug） cargo build --release # 启用完整的 OPSEC stack 编译 BOF ./target/release/entc compile example/bof_pslist.etpy --type=bof --opsec=all # 在本地 test harness 下运行它 ./target/release/bof-runner example/bin/bof_pslist.x64.o ``` 对于预编译二进制文件：从 [GitHub Releases](https://github.com/entropykit/entropia/releases) 获取并跳过 `cargo build` 步骤。你可以在 [docs.entropykit.com/getting-started/installation](https://docs.entropykit.com/getting-started/installation) 找到包含 的完整指南。 ## 为什么会有这个项目 大多数红队产出物通过由三到四个工具链式连接的构建流水线交付：用于源码的 C 编译器、链接器、像 DonutGen 或 sRDI 这样的位置无关性转换工具，加上你为了事后硬塞 OPSEC 技巧而自己编写的任何东西。Entropia 将该流水线压缩为单个编译器，同时提供现代高级语言的体验。 输出结果就是你真正想要的产出物，无论是位置无关的 shellcode blob 还是 Cobalt Strike Beacon Object File，都无需任何后处理步骤。这门语言非常精简，一个下午就能学会，同时也足够完善，可以用于交付生产级别的工具。整个 OPSEC 栈以编译器标志的形式提供，而不是构建后修补。 因为编译器端到端拥有整个流水线，所以一切都井然有序。在 `asm { ... }` 中手写的 PEB 遍历、`[Hook("LIB$Func")]` 属性、`[Stage(Init)]` 启动 hook 和 `--opsec=all` 共享相同的内部表示，并且不会相互冲突。你交付的产出物就是编译器生成的产出物，通过每次构建的随机种子进行多态变形，因此同一源码的两次连续构建在字节级别的差异达到 67% 到 78%。 ## 示例 ### Shellcode (`fn main` 入口) ``` use_c "winuser.h"; fn main() -> int { User32.MessageBoxA(0, "hello", "entropia", 0); ret 0; } ``` ``` entc compile hello.etpy # writes hello.bin entc-debug hello.bin # run under the local loader ``` ### BOF (`fn go` 入口) ``` use bof; fn go(args: char*, len: int) -> void { var parser: datap; BeaconDataParse(&parser, args, len); var target: char* = BeaconDataExtract(&parser, 0); BeaconPrintf(CALLBACK_OUTPUT, str.format("hello, {s}\n", target)); ret; } ``` ``` entc compile hello.etpy --type=bof bof-runner hello.x64.o --zarg "operator" ``` ### 内联汇编 + 真正的 PEB 遍历 ``` fn read_peb() -> u64 { var peb: u64; asm { mov rax, gs:[0x60]; mov %peb, rax; } ret peb; } ``` ### 一行代码实现 OPSEC 预检 ``` use opsec_unhook; // restores ntdll text section from disk use opsec_etw; // patches Etw* hot paths use opsec_amsi; // patches AmsiScanBuffer return fn go(args: char*, len: int) -> void { // Pre-flight modules run before this line via [Stage(Init)]. // Your code runs in a clean process. ret; } ``` ## OPSEC 栈 以下每项技术均可通过 `--opsec=` 启用。构建种子 （默认为 `--seed=random`）驱动每一个随机化选择。 | 标志 | 作用 | 模式 | |---|---|---| | `poly` | 在 codegen 后重写指令。`xor` 变 `sub`，`mov MR` 变 `RM` 再变 `lea`，`test` 变 `or` 再变 `and`，NOP run 重新分解。 | 两者皆有 | | `nop_sled` | 使用随机多字节 NOP 填充每个函数入口。移动所有下游的字节偏移量，从而使整个二进制文件的模糊哈希值在构建之间产生漂移。 | 两者皆有 | | `strings_xor` | 使用每次构建的随机密钥对 `.rdata` 和 `.data` 进行 XOR 加密。解密器在用户代码之前运行。 | shellcode | | `stack_strings` | 在栈上而非 `.rdata` 中实现字符串常量实例化。从产出物中消除明文字符串。 | 两者皆有 | | `direct_syscalls` | 自动导入 HellsGate 风格的 stub。每个 `Ntdll.X(...)` 都在我们代码区域内的 `syscall` 中进行派发。 | 两者皆有 | | `indirect_syscalls` | 自动导入间接系统调用 stub。每个 `Ntdll.X(...)` 都跳转到 ntdll 自身内部的 `syscall;ret` gadget。 | 两者皆有 | | `hashed_imports` | 移除 BOF 中所有的 `__imp_LIB$Func` 外部符号。Win32 导入在运行时通过 PEB 遍历加上 LoadLibraryA 加上 GetProcAddress 解析。 | BOF | 栈欺骗（Draugr 风格的合成调用帧）和操作员可选的 sleep masks 可通过显式的 `use opsec_stack_spoof;` 和 `use opsec_sleep_mask;` 导入使用。 ## 包含哪些组件 | 二进制文件 | 作用 | |---|---| | `entc` | 编译器。接收 `.etpy` 源文件，生成 `.bin` shellcode 或 `.x64.o` BOF。 | | `bof-runner` | 用于 BOF 的本地测试工具。应用重定位，填充 Beacon API stub，并调用 `go(args, len)`。 | | `entc-debug` | Debug Adapter Protocol 服务器。支持 VS Code 的 F5 和 F9 功能。 | | `entc-win32gen` | 从 Microsoft 的 win32metadata 生成类型化的 C 头文件。 | | VS Code 扩展 | 语法高亮、F5 构建并运行、F9 在内联汇编中设置断点。位于 `tools/vscode-entropykit/`。 | ## 从源码构建 ### 前置条件 - Rust 1.75 或更高版本 ([rustup.rs](https://rustup.rs))。 - Windows x86-64，用于运行生成的二进制文件。编译器本身也可以 在 Linux 和 macOS 上构建并运行，但输出目标为 Windows。 ### 构建所有内容 ``` cargo build --release ``` 三个二进制文件会存放在 `target/release/` 下： ``` target/release/entc.exe target/release/bof-runner.exe target/release/entc-debug.exe ``` ### 构建单个二进制文件 ``` cargo build --release -p entropykit # entc only cargo build --release -p bof-runner # local BOF harness only cargo build --release -p entc-debug # DAP server only ``` ### 安装 VS Code 扩展 ``` python tools/vscode-entropykit/build.py install ``` 重新加载 VS Code（通过命令面板执行 "Developer: Reload Window"）以使其生效。 其他操作（`uninstall`、`status`、`vsix`）详见 [docs.entropykit.com/getting-started/installation](https://docs.entropykit.com/getting-started/installation)。 即将登陆 VS Code marketplace ## 文档 参考文档和指南位于 **[docs.entropykit.com](https://docs.entropykit.com)**。 | 章节 | 涵盖内容 | |---|---| | [入门指南](https://docs.entropykit.com/getting-started/installation) | 安装、项目配置、第一个程序、CLI 参考、每个编译器标志。 | | [语言](https://docs.entropykit.com/language/overview) | 类型、控制流、结构体、指针、索引、类型转换、try 和 catch、内联汇编、内置函数、垃圾回收器。 | | [模块和标准库](https://docs.entropykit.com/modules/use) | `use` 和 `use_c`，标准库中包含的内容。 | | [Win32](https://docs.entropykit.com/win32/calling-apis) | `Lib.Function(...)` 调用如何端到端运行。自定义解析器。 | | [BOF 模式](https://docs.entropykit.com/bof/overview) | `go(args, len)`、Beacon API、自动生成的 Aggressor 脚本、本地测试、F5 调试。 | | [OPSEC](https://docs.entropykit.com/opsec/overview) | 通过示例和权衡解释每个标志。 | | [高级功能](https://docs.entropykit.com/advanced/overrides) | `[Override(Slot)]`、`[Hook(...)]`、生命周期阶段。 | 每个带标签的发布版本都包含一份独立的 PDF 格式文档快照。 ## 状态 Entropia 处于 1.0 版本之前的状态，其表层功能仍在不断变动。预期编译器内部结构在提交之间会发生变化；源码级别的语言表面已经足够稳定，因此预期此 README 中的示例能够继续正常工作。 以下是大致已完成和正在进行的工作： | 领域 | 状态 | |---|---| | 编译器前端 (lexer、parser、type checker) | 稳定。 | | Codegen 和 encoder | 稳定。根据需要添加新的助记符。 | | BOF 模式 | 稳定。 | | Shellcode 模式 | 稳定。 | | OPSEC 栈 (poly、syscalls、sleep masks、hashed imports) | 稳定。 | | VS Code F5 / F9 流程 | 稳定。 | | 垃圾回收器 | 稳定。对于对体积敏感的构建，建议默认使用手动模式。 | | Linux / macOS 工具链支持 | 仅支持构建。生成的产出物始终面向 Windows x86-64。 | | 测试 | 待实现。 | | ARM64 后端 | 未开始。 | ## 授权与负责任的使用 Entropia 是一种双重用途的安全工具。示例 BOF 实现了有据可查的攻击性原语（进程枚举、token 模拟、远程注入、LSASS 转储、静默 AMSI 和 ETW），你可以在主流技术参考（如 nanodump、mimikatz、TrustedSec 的 CS-Situational-Awareness-BOF 集合以及 Cobalt Strike 的标准 BOF 库）中找到这些内容。 仅在经过授权的红队交战、CTF 环境和安全研究中使用 Entropia。作者不对滥用行为承担任何责任。

标签：SCP, Shellcode, Subfinder, 位置无关代码, 可视化界面, 客户端加密, 技术调研, 端点可见性, 编译器