Obscyrizz/luau-deobf-pro
GitHub: Obscyrizz/luau-deobf-pro
这是一个针对Roblox/Luau脚本的反混淆工具，用于在Android Termux上进行安全分析和逆向工程。
Stars: 0 | Forks: 0
# Luau 反混淆专业版 - Termux 版
**针对 Android Termux 优化的专业级 Lua/Luau 反混淆工具集**
一套全面的多层次脚本分析工具，用于逆向工程分析混淆的 Lua 脚本，特别是来自 Roblox 执行器和游戏脚本的混淆代码。
## 🚀 功能特性
### Android/Termux 优化
- ⚡ 轻量级依赖（仅需 Lua 5.1 + Python 3）
- ⚡ 高效内存使用与大小限制
- ⚡ 完全离线运行
- ⚡ 存储集成，便于文件访问
## 📋 前置条件
**必需项：**
**可选项：**
- Termux:API 以获得增强功能
- 文本编辑器（设置中已包含 nano）
## 🛠️ 安装说明
### 选项 1：自动化安装（推荐）
```
# 下载并运行安装脚本
curl -O https://raw.githubusercontent.com/Obscyrizz/luau-deobf-pro/main/setup_termux.sh
bash setup_termux.sh
```
### 选项 2：手动安装
#### 步骤 1：更新 Termux 并安装依赖
```
# 更新软件包列表
pkg update -y && pkg upgrade -y
# 安装所需软件包
pkg install lua5.1 python git nano -y
# 启用存储访问权限（Downloads 文件夹所需）
termux-setup-storage
```
**注意：** 当提示时，请授予 Termux 存储权限。
#### 步骤 2：克隆或下载工具
**选项 A：使用 Git**
```
cd ~
git clone https://github.com/Obscyrizz/luau-deobf-pro.git
cd luau-deobf-pro
```
**选项 B：手动下载**
```
cd ~
mkdir luau-deobf-pro
cd luau-deobf-pro
# 单独下载文件（如果本地已有）
# 或使用以下手动创建文件的方法
```
#### 步骤 3：设置脚本可执行权限
```
chmod +x deobfuscate.py
chmod +x setup_termux.sh # if using setup script
```
#### 步骤 4：验证安装
```
python deobfuscate.py --help
```
你应该看到工具横幅和使用说明。
## 📖 使用方法
### 基础用法
```
# 反混淆脚本
python deobfuscate.py script.lua
# 从 Downloads 文件夹
python deobfuscate.py ~/storage/downloads/obfuscated.lua
# 从当前目录
python deobfuscate.py ./suspicious_script.luau
```
### 执行过程
1. **工作区设置** - 创建隔离的分析环境
2. **环境模拟** - 设置虚假的 Roblox/执行器 API
3. **钩子安装** - 拦截所有 `loadstring()` 调用
4. **执行** - 安全地运行脚本
5. **分析** - 解码字符串、提取 URL、检测模式
6. **输出生成** - 创建编号的转储文件 + 报告
### 输出结构
```
workspace/
├── output/
│ ├── dump_0001_main_chunk.lua # First decoded layer
│ ├── dump_0002_http_loader.lua # Second layer
│ ├── dump_0003_payload.lua # Final payload
│ └── ...
├── ANALYSIS_REPORT.txt # Full analysis summary
└── config.lua # Configuration used
```
### 阅读输出文件
每个转储文件包括：
- **头部**：元数据（时间戳、大小、发现的 URL）
- **解码字符串**：自动解混淆的内容
- **虚拟机模式**：检测到的混淆技术
- **源代码**：实际解码后的脚本
```
# 查看第一个转储文件
nano workspace/output/dump_0001_*.lua
# 按大小列出所有转储文件
ls -lhS workspace/output/
# 在所有转储文件中搜索特定字符串
grep -r "loadstring" workspace/output/
# 统计转储文件总数
ls workspace/output/dump_*.lua | wc -l
```
## ⚙️ 配置
编辑 `config.lua` 以自定义行为：
```
-- config.lua
return {
-- Output settings
output_dir = "output", -- Where dumps are saved
max_filename_length = 50, -- Truncate long names
include_timestamps = true, -- Add timestamps to logs
-- Dumping behavior
dump_all_loadstring = true, -- Capture every loadstring call
decode_string_char = true, -- Auto-decode string.char()
track_http_requests = true, -- Log all HTTP attempts
-- Safety limits (Android optimization)
max_chunk_size = 5 * 1024 * 1024, -- 5MB per chunk
max_dumps_per_run = 500, -- Stop after 500 dumps
-- Verbosity
verbose = true, -- Detailed logging
show_stack_traces = false -- Debug mode
}
```
**设备内存受限？** 请减少限制：
```
max_chunk_size = 1 * 1024 * 1024, -- 1MB
max_dumps_per_run = 100, -- 100 dumps
```
## 🎯 高级功能
### 1. 字符串解混淆
自动解码：
```
-- Pattern 1: string.char
string.char(104, 116, 116, 112, 115) → "https"
-- Pattern 2: Escape sequences
"\104\116\116\112\115" → "https"
-- Pattern 3: Table-based
{104, 116, 116, 112, 115} → "https"
```
### 2. 虚拟机检测
识别：
- 字节码解释器
- 基于栈的虚拟机
- 指令解码器
- 常量表
- 函数包装器
### 3. URL 发现
查找：
- 标准 URL：`http://example.com`
- URL 编码：`%68%74%74%70`
- 隐藏在字符串中：`string.char(104,116,116,112)..".com"`
### 4. 多层次分析
```
Layer 1: Outer obfuscator
↓
Layer 2: String decoder
↓
Layer 3: HTTP loader
↓
Layer 4: Final payload
```
每一层都会单独转储并进行分析。
## 🔍 示例场景
### 场景 1：简单混淆脚本
```
$ python deobfuscate.py simple_script.lua
Analysis Complete
Status: SUCCESS
Time: 1.23s
Dumps: 3
[✓] Output location: workspace/output/
View dumps: ls -lh workspace/output/
Read first: nano workspace/output/dump_0001_main.lua
```
### 场景 2：多阶段加载器
```
$ python deobfuscate.py loader.lua
Analysis Complete
Status: SUCCESS
Time: 4.56s
Dumps: 12
[!] Found 3 unique URL(s):
https://pastebin.com/raw/abc123
https://raw.githubusercontent.com/user/repo/script.lua
https://api.example.com/v1/payload
```
### 场景 3：虚拟机保护脚本
```
$ python deobfuscate.py protected.lua
Analysis Complete
Status: SUCCESS
Time: 8.91s
Dumps: 45
VM Patterns detected:
- bytecode_vm
- stack_based
- instruction_decode
- constants_table
```
## 🐛 故障排除
### 问题："Lua 未找到"
**解决方案：**
```
# 尝试使用 Lua 代替 lua5.1
pkg install lua -y
# 验证安装
lua -v
```
### 问题：目标文件 "未找到"
**解决方案：**
```
# 检查文件是否存在
ls -la ~/storage/downloads/
# 使用绝对路径
python deobfuscate.py ~/storage/downloads/script.lua
# 或复制到工作目录
cp ~/storage/downloads/script.lua .
python deobfuscate.py script.lua
```
### 问题：内存不足 / Termux 崩溃
**解决方案：**
```
# 编辑 config.lua 并降低限制
nano config.lua
# 更改为：
max_chunk_size = 1 * 1024 * 1024, -- 1MB instead of 5MB
max_dumps_per_run = 50, -- 50 instead of 500
# 运行前关闭其他应用程序
```
### 问题："模块未找到" 错误
**解决方案：**
```
# 确保目录结构正确
cd ~/luau-deobf-pro
ls -la
# 应看到：
# config.lua
# deobfuscate.py
# core/
# utils/
# 从项目根目录重新运行
python deobfuscate.py target.lua
```
### 问题：脚本运行了但未生成转储文件
**可能原因：**
1. 脚本未使用 `loadstring()` - 某些脚本只是纯 Lua 代码
2. 脚本检测到了分析环境 - 尝试修改 Roblox 模拟
3. 目标脚本存在语法错误 - 检查 stderr 输出
**解决方案：**
```
# 检查是否已进行过混淆
file target.lua
head -20 target.lua
# 查看标准错误输出
cat workspace/ANALYSIS_REPORT.txt
# 尝试详细模式
nano config.lua # Set verbose = true
```
### 问题：权限被拒绝
**解决方案：**
```
# 赋予脚本可执行权限
chmod +x deobfuscate.py
# 修复工作区权限
chmod -R 755 workspace/
# 如遇存储问题
termux-setup-storage
```
## 🛡️ 安全与道德
### 本工具适用于：
✅ 对您拥有/已获授权分析的脚本进行安全研究
✅ 用于学习混淆技术的教育目的
✅ 在受控环境中进行恶意软件分析
✅ 恢复您自己被混淆的代码
### 本工具不适用于：
❌ 未经授权分析脚本
❌ 绕过您不拥有的软件的拷贝保护
❌ 创建恶意软件或漏洞利用
❌ 违反服务条款
### 安全功能：
- **无实际 HTTP 请求** - 所有网络调用都被拦截并仅记录日志
- **文件系统模拟** - 不会发生真实的文件操作
- **沙箱化执行** - 脚本在隔离的 Lua 环境中运行
- **大小限制** - 防止内存耗尽
**⚠️ 警告：** 请始终在安全环境中分析不受信任的脚本。虽然此工具可防止大多数恶意操作，但不能保证 100% 安全。
## 📚 理解输出
### 转储文件头部
```
--[[
Captured from: main_chunk
Timestamp: 2025-05-18 14:30:45
Size: 15823 bytes (342 lines)
Decoded strings found:
- https://pastebin.com/raw/abc123
- game:HttpGet
- loadstring
URLs found:
- https://pastebin.com/raw/abc123
VM Patterns detected:
- bytecode_vm
--]]
```
### 分析报告结构
```
═══════════════════════════════════════════════
LUAU DEOBFUSCATION ANALYSIS REPORT
═══════════════════════════════════════════════
Target File: obfuscated.lua
File Size: 45,231 bytes
Analysis Time: 3.21 seconds
Status: SUCCESS
Dumps Created: 8
URLs Found: 2
Discovered URLs:
- https://pastebin.com/raw/abc123
- https://example.com/payload.txt
═══════════════════════════════════════════════
FULL OUTPUT LOG
═══════════════════════════════════════════════
[INFO] Luau Deobfuscator initialized
[DUMP] #1 -> dump_0001_main.lua (12843 bytes)
...
```
## 🔄 工作流示例
### 标准分析工作流
```
# 1. 复制待分析脚本
cp ~/storage/downloads/script.lua ~/luau-deobf-pro/
# 2. 运行反混淆
cd ~/luau-deobf-pro
python deobfuscate.py script.lua
# 3. 审阅分析报告
cat workspace/ANALYSIS_REPORT.txt
# 4. 检查转储文件
ls workspace/output/
nano workspace/output/dump_0001_*.lua
# 5. 搜索特定模式
grep -r "http" workspace/output/
grep -r "loadstring" workspace/output/
# 6. 清理以准备下次运行
rm -rf workspace/
```
### 批量处理多个脚本
```
# 处理文件夹中的所有脚本
for script in ~/storage/downloads/*.lua; do
echo "Processing: $script"
python deobfuscate.py "$script"
mv workspace/output "results_$(basename $script .lua)"
rm -rf workspace/
done
```
### 查找恶意指标
```
# 运行反混淆后：
# 查找所有 URLs
grep -rh "https\?://" workspace/output/ | sort | uniq
# 查找特定执行器的调用
grep -r "getgenv\|getrenv\|getrawmetatable" workspace/output/
# 查找文件系统访问尝试
grep -r "readfile\|writefile\|makefolder" workspace/output/
# 查找可疑函数名
grep -r "bypass\|exploit\|hack\|steal\|admin" workspace/output/
```
## 🎓 提示与最佳实践
### 性能提示
1. **关闭其他应用**，分析大脚本前
2. **使用较小的大小限制**（在 config.lua 中）以提高稳定性
3. **低内存设备一次处理一个脚本**
4. **保持 Termux 更新**：`pkg upgrade`
### 分析提示
1. **从 dump_0001 开始** - 通常最易读
2. **先查找 URL** - 常揭示有效载荷来源
3. **检查虚拟机模式** - 表示存在多层
4. **比较连续的转储文件** - 显示解混淆进展
5. **搜索 "loadstring" 等字符串** - 找到递归加载器
### 整理结果
```
# 创建结构化输出目录
mkdir -p ~/analysis/{malicious,benign,unknown}
# 移动已分析结果
mv workspace/output ~/analysis/malicious/script_20250518/
# 记录笔记
echo "Found keylogger payload" > ~/analysis/malicious/script_20250518/NOTES.txt
```
## 🆘 获取帮助
### 快速参考
```
# 显示帮助
python deobfuscate.py --help
# 检查 Lua 版本
lua5.1 -v
# 验证项目结构
ls -R ~/luau-deobf-pro
# 查看近期错误
cat workspace/ANALYSIS_REPORT.txt | grep ERROR
# 使用最小化脚本测试
echo 'print("test")' > test.lua
python deobfuscate.py test.lua
```
### 常用命令
```
# 安装缺失的包
pkg install lua5.1 python git -y
# 修复权限
chmod +x deobfuscate.py
chmod -R 755 workspace/
# 清理工作区
rm -rf workspace/
# 更新工具（如使用 git）
git pull origin main
```
## 📝 技术细节
### 架构
```
deobfuscate.py (Orchestrator)
↓
core/dumper.lua (Hook Engine)
↓
utils/string_decoder.lua (Pattern Analysis)
↓
config.lua (User Settings)
↓
workspace/output/ (Results)
```
### 工作原理
1. **钩子安装**：替换全局的 `loadstring()` 和 `load()`
2. **环境模拟**：创建虚假的 Roblox/执行器 API
3. **执行**：在受控环境中运行目标脚本
4. **拦截**：捕获所有动态加载的代码
5. **分析**：解码字符串，提取元数据
6. **输出**：将每一层保存为单独的文件
### 支持的混淆类型
- ✅ 字符串连接
- ✅ 字符编码 (`string.char`)
- ✅ 转义序列 (`\104\116...`)
- ✅ 基于表的编码
- ✅ Base64 编码
- ✅ 多阶段加载器
- ✅ 基于虚拟机的保护（部分支持）
- ✅ 元表滥用
- ✅ 环境操控
### 局限性
- ❌ 无法完全逆转基于字节码的虚拟机（仅捕获输出）
- ❌ 某些控制流混淆保持不变
- ❌ 重度基于元表的保护可能需要手动分析
- ❌ 非常大的脚本（>50MB）在低内存设备上可能崩溃
## 🤝 参与贡献
发现错误或想添加功能？欢迎贡献！
```
# Fork 仓库并克隆
git clone https://github.com/yourusername/luau-deobf-pro.git
# 创建功能分支
git checkout -b feature/amazing-feature
# 进行修改并测试
python deobfuscate.py test_scripts/sample.lua
# 提交并推送
git commit -m "Add amazing feature"
git push origin feature/amazing-feature
# 打开拉取请求
```
## 📄 许可证
MIT 许可证 - 详情请见 LICENSE 文件
## 🙏 致谢
- Lua 5.1 社区
- Termux 项目
- Roblox 安全研究人员
- 开源贡献者
## 📞 支持
**问题反馈：** https://github.com/yourusername/luau-deobf-pro/issues
**讨论交流：** https://github.com/yourusername/luau-deobf-pro/discussions
**为 Android 逆向工程师用心打造 ❤️**
*最后更新于：2025年5月18日*
标签：Android优化, AST操纵, Luau脚本, Lua语言, Roblox逆向, Termux应用, TLS抓取, 云资产清单, 代码混淆, 反混淆工具, 多层分析, 执行器分析, 游戏安全, 游戏脚本, 离线工具, 网络安全研究, 脚本分析, 解混淆技术, 软件安全, 轻量级软件, 逆向工程, 高级技术