PumbaaDev/luau-decompiler

# luau-decompiler [](https://github.com/PumbaaDev/luau-decompiler/actions/workflows/ci.yml) [](LICENSE) [](https://www.rust-lang.org) 一个快速、完全离线的 **Luau bytecode 反编译器**、反汇编器和代码混淆器，使用 Rust 编写。 只需输入编译后的 Luau bytecode，即可还原出可读的 Luau 源代码。所有操作均在本地 100% 运行，无需网络，也无需任何外部服务。 ## 特性 - **反编译器** — 将 Luau bytecode 还原为可读的 Luau 源代码：基于寄存器的 VM 状态、控制流重建（if/while/repeat/for）、table、upvalue 和常量恢复。指令集中的每个 opcode 都有对应的处理程序，包括 Roblox 的 bytecode 扩展。 - 支持 **Bytecode 版本 3–8**。 - **反汇编器** — 提供可读的 opcode 列表，带有可选的调试信息（行号、本地变量名）以及 opmap 重映射诊断视图。 - **信息** — 将 bytecode 元数据（protos、字符串、参数、栈大小）以文本或 JSON 格式导出。 - **混淆器** (`luau-compiler`) — 一个配套的保护器，用于编译/混淆 Luau（控制流平坦化、常量加密、操作数编码、标识符重命名、垃圾代码插入）。 - **批量与监听** 模式 — 对整个文件夹进行反编译，或在文件出现时自动进行反编译。 - **验证与比较** — 对反编译输出进行语法检查，并通过相似度评分对两个源代码进行 diff 比较。 ## 安装 通过源码构建（需要 [Rust 工具链](https://rustup.rs)）： ``` git clone https://github.com/PumbaaDev/luau-decompiler cd luau-decompiler cargo build --release ``` 生成的二进制文件位于 `target/release/luau-decompiler`。 ## 用法 ``` # 将单个 bytecode 文件反编译为 Luau 源码（打印到 stdout） luau-decompiler script.bin # 写入文件 luau-decompiler script.bin -o script.lua # 改为进行反汇编 luau-decompiler disassemble script.bin --debug-info # 将 bytecode 元数据作为 JSON luau-decompiler info script.bin --json # 批量反编译文件夹中的每一个 bytecode 文件 luau-decompiler batch ./bytecode -o ./out # 监视文件夹并在文件落地时进行反编译 luau-decompiler watch ./drop -o ./out # 对 Luau 文件进行语法检查 luau-decompiler validate script.lua # 对比两个 Luau 源码并给出相似度评分 luau-decompiler compare original.lua decompiled.lua ``` 运行 `luau-decompiler --help`（或对任何子命令使用 `--help`）以获取完整的选项列表。 ## 端到端尝试 下面的两个演示都是针对本仓库中已有的文件运行的——无需外部 Luau 工具链。 ### 1. 查看反编译器还原源代码 反编译器接收**标准的 Luau bytecode**（v3–8），例如官方 `luau-compile --binary` 的输出，或是 Luau runtime 的 `string.dump`。为了保持完全独立，内置示例会在内存中组装一个小的 bytecode 块，并使用与 CLI 相同的引擎将其还原为源代码： ``` cargo run -p luau-core --example decompile_demo ``` 输出： ``` for i = 1, 10 do local function run() return i end local tbl = { run = run } tbl.run() end ``` 一旦你有了真正的 bytecode 文件，就可以直接使用 `luau-decompiler script.luac` 进行反编译（或通过管道输入：`luau-decompiler decompile - < script.luac`）。 ### 2. 使用配套的编译器保护脚本 `luau-compiler`（即 `luau-protect` 二进制文件）将一个 `.lua` 文件编译成一个独立、混淆的 Luau 脚本 —— 常量被加密，控制流隐藏在解释器循环之后： ``` cargo run --release -p luau-compiler -- crates/luau-compiler/tests/fixtures/hello.lua -o hello.protected.lua ``` 它会打印 `luau-protect: wrote bytes to hello.protected.lua`，其结果是有效的 Luau 代码，可以在原始代码能够运行的任何地方运行。添加 `--max` 以启用所有保护阶段。 ## 正确性 反编译本质上是有损的：变量名、注释和一些结构在编译时会被丢弃，因此没有反编译器能完全重现原始源代码。“看起来合理”因而是一个很弱的标准，而这正是大多数反编译器所采用的衡量标准。 本项目使用了一个更严格的标准：**语义往返测试**。对于测试语料库中的每个程序，测试套件都会： 1. 使用 Luau 解释器运行原始代码并记录其输出， 2. 将其编译为 bytecode， 3. 将该 bytecode 反编译回源代码， 4. **运行还原后的源代码**，并且 5. 要求其输出与原始输出完全一致。 任何不完全匹配的情况都被视为失败，包括那些仅仅是看起来正确的输出。 这能捕获大量视觉检查容易遗漏的 bug 类别：丢失的循环增量、静默停止捕获的 upvalue、差一位的 table 构建、折叠到错误分支的代码块。 语料库涵盖了算术和运算符、字符串、table、控制流，以及闭包 / varargs / metatable / OOP 模式。它是故意设计成充满对抗性的，而不是简单的理想路径，其通过率被视为项目真正的质量指标。 ## 项目结构 | Crate | 描述 | |-------|------------| | `luau-core` | 反编译器引擎 —— 解析器、opcode 映射、AST、提升器和发射器。 | | `luau-cli` | 命令行前端 (`luau-decompiler`)。 | | `luau-compiler` | 配套的 Luau 混淆器/保护器。 | ## 工作原理 `luau-core` 解析 bytecode 块（32 位指令字、ABC/AD/E 编码、常量和 proto 表），重建每个 proto 的控制流图，并运行一个寄存器跟踪提升器，将扁平的指令流重新转换为结构化的 Luau 语句和表达式，最后由发射器进行美观打印。 ## 许可证 MIT — 详见 [LICENSE](LICENSE)。 ## 贡献 欢迎提交 Issue 和 pull request。如果你遇到反编译不正确的 bytecode 文件，提供一个最小复现示例（该 bytecode 以及预期的源代码）是你能提交的最有用的内容。

标签：Findomain, Luau, Rust, 云资产清单, 代码混淆, 反汇编器, 反编译器, 可视化界面, 编译器工具, 网络流量审计, 逆向工程, 通知系统