Chaobs/unity-es3-cracker
GitHub: Chaobs/unity-es3-cracker
一个用于逆向恢复并暴力破解 Unity Easy Save 3 加密存档文件 AES 密码的图形化与命令行工具。
Stars: 1 | Forks: 0
# Unity Easy Save 3 存档密码破解工具
一个图形化 / 命令行工具，用于**逆向工程并恢复**使用 **Easy Save 3 (ES3)** 插件创建的 Unity 游戏存档文件的**加密密码**。它能自动从游戏目录中收集候选密码，暴力破解保护 `.es3` 存档的 AES 密钥，并显示解密后的内容预览。
## 功能特性
- **图形界面 (Tkinter)：** 选择游戏目录和存档文件，一键破解，并带有实时进度和日志。
- **批量处理：** 可同时选择多个 `.es3` 文件。
- **自动收集候选密码：**
1. 内置包含常见 ES3 / Unity 密码的字典；
2. 通过 **dnlib** 解析游戏的 `.dll` 并提取 C# 字符串字面量（密码最可能存放的位置）；
3. 扫描 Unity `.assets` 资源包以查找明文字符串（ES3 的默认加密密码通常作为 `ScriptableObject` 序列化在资源中）。
- **精确算法：** 忠实还原 ES3 加密方式（AES-128/256-CBC，PBKDF2-HMAC-SHA1，salt = 文件 IV）。详情请参阅下方的“工作原理”。
- **解密预览：** 成功后，显示解密存档的前 2000 个字符（ES3 的自定义序列化格式）。
- **CLI 模式：** 适用于批量 / 自动化 / 无界面环境。
- **双语支持 (English / 中文)：** 默认为英语。图形界面有一键切换按钮（右上角）；CLI 通过 `--lang en|zh` 进行切换。
## 双语支持
| 入口 | 默认 | 切换方式 |
| --- | --- | --- |
| GUI | 英语 | 一键切换按钮（右上角）—— 所有界面文本、标签、提示、日志和结果都会立即刷新 |
| CLI | 英语 | `--lang zh` 输出简体中文；`--lang en`（默认）输出英语 |
## 工作原理
ES3 的 AES 加密格式（从游戏程序集中逆向工程得出，并在指令级别进行了确认）：
```
IV = first 16 bytes of the save file (random per file)
Key = PBKDF2-HMAC-SHA1(password, salt = IV, iterations = 100, dklen = 16) # AES-128
file = IV || AES-CBC(Key, IV).Encrypt(PKCS7(plaintext))
```
关键陷阱：**salt 并不是一个固定的字符串 —— 它是文件自身的 IV。** 因此，每个存档文件都会派生出不同的密钥，使用“固定 salt”进行派生永远无法打开文件。这也是许多在线 ES3 示例与真实游戏实现之间最大的差异所在。
破解流程：
1. 读取存档 → 解析文件头（大小、IV、是否看似被加密）；
2. 从游戏目录构建候选集合（DLL 字面量 + `.assets` 字符串 + 内置字典）；
3. 对于每个候选密码：执行 `解密 → PKCS7 检查 → 明文可读性 / ES3 标记检测`；
4. 通过验证且置信度得分最高的候选密码即为最终结果。
## 环境要求
| 组件 | 说明 |
|-----------|-------|
| Python | 3.8+（推荐 3.11+） |
| 操作系统 | Windows（通过 PowerShell 桥接调用 dnlib；在非 Windows 系统上会自动回退到字节扫描，仅会丢失 DLL 字面量提取功能） |
| `pycryptodome` | 内置于 `libs/pycryptodome/`，无需手动安装 |
| `dnlib.dll` | 内置于 `libs/dnlib.dll`（开源 .NET 程序集解析器） |
## 安装说明
无需安装 —— 依赖项已全部内置：
```
git clone https://github.com/Chaobs/unity-es3-cracker.git
cd unity-es3-cracker
python main.py
```
如果你的 Python 版本与内置的 `pycryptodome` 不兼容（极少发生），请手动重新安装：
```
pip install -r requirements.txt
```
## 使用说明
### 图形界面
```
python main.py
```
1. **游戏目录：** 点击“浏览”选择游戏的安装根目录（用于收集候选密码）。留空则仅使用内置的常见密码。
2. **存档文件：** 点击“选择”选取一个或多个 `.es3` 文件（支持批量处理）。
3. 点击 **开始破解**，等待进度条和日志运行完毕。
4. 结果面板会列出每个存档的**恢复密码**（按置信度排序）；点击某项即可在右侧查看**解密预览**。
5. 选中一个密码并点击 **复制选中的密码** 即可使用（例如配合 ES3 编辑器或你自己的脚本修改存档）。你也可以直接点击或右键点击密码行进行复制。
### 命令行模式
```
# 游戏目录 + 多个存档
python -m src.cli --game-dir "D:/Games/NTR Soccer" --saves save1.es3 save2.es3
# 仅 Built-in dictionary，单个存档，JSON 输出
python -m src.cli --saves save3.es3 --json
```
## 项目结构
```
unity-es3-cracker/
├── main.py # Entry point (launches the GUI)
├── requirements.txt # Python dependencies
├── README.md
├── LICENSE
├── src/
│ ├── es3_crypto.py # ES3 AES encrypt/decrypt / validation / header parsing
│ ├── candidates.py # Candidate password harvesting (dnlib + .assets + built-in dict)
│ ├── cracker.py # Crack orchestration (single file / batch)
│ ├── gui.py # Tkinter GUI
│ └── cli.py # Command-line interface
├── libs/
│ ├── dnlib.dll # Open-source .NET assembly parser (extracts DLL strings)
│ ├── extract_strings.ps1 # PowerShell bridge that invokes dnlib
│ └── pycryptodome/ # Bundled pycryptodome (Crypto package)
└── docs/
├── USAGE.md # Detailed usage guide (EN/中文)
└── DEVELOPMENT.md # Development & algorithm notes
```
## 依赖项
- **dnlib** (MIT, )：在 PowerShell 中通过 `libs/extract_strings.ps1` 加载，用于从游戏 DLL 中提取 C# 字符串字面量。仅限 Windows；其他系统自动回退。
- **pycryptodome** (BSD, )：提供 AES / PBKDF2 支持，内置于 `libs/pycryptodome/`，在启动时会自动添加到 `sys.path` 中。
## 许可证
MIT —— 详见 [LICENSE](LICENSE)。
# Unity Easy Save 3 存档密码破解工具
一个用于**逆向破解 Unity 游戏（使用 Easy Save 3 插件）加密存档**的图形化 / 命令行工具。
它能自动从游戏目录中提取候选密码，暴力破解 `.es3` 存档的加密密钥，并展示解密后的内容预览。
## 功能特性
- **图形界面（GUI）**：选择游戏目录与存档文件，一键破解，实时进度与日志。
- **批量处理**：可同时选择多个 `.es3` 文件。
- **自动候选提取**：
1. 内置常见 ES3 / Unity 密码字典；
2. 通过 **dnlib** 解析游戏 `.dll`，提取 C# 字符串字面量（密码最可能的来源）；
3. 扫描 Unity `.assets` 资源包中的明文字符串（ES3 默认加密密码常以 `ScriptableObject` 形式序列化在资源里）。
- **算法实现**：精确还原 ES3 加密（AES‑128/256‑CBC，PBKDF2‑HMAC‑SHA1，salt = 文件 IV），详见下文「工作原理」。
- **解密预览**：破解成功后直接展示存档明文（ES3 自定义序列化格式）前 2000 字符。
- **命令行模式**：适合批量 / 自动化 / 无界面环境。
- **双语支持（中 / 英）**：默认英文。图形界面右上角有一键切换按钮，点击后界面文本、按钮标签、提示、日志与破解结果立即更新为对应语言；命令行通过 `--lang en|zh` 切换输出语言。
## 双语支持 / Bilingual
| 入口 | 默认语言 | 切换方式 |
| --- | --- | --- |
| 图形界面 (GUI) | 英文 | 点击右上角语言切换按钮，一键在中英文间切换，所有界面与结果即时刷新 |
| 命令行 (CLI) | 英文 | `--lang zh` 输出简体中文，`--lang en`（默认）输出英文 |
## 工作原理
Easy Save 3 的 AES 加密格式（逆向自游戏程序集，指令级确认）：
```
IV = 存档文件的前 16 字节（每个文件随机生成）
Key = PBKDF2-HMAC-SHA1(password, salt = IV, iterations = 100, dklen = 16) # AES-128
文件 = IV || AES-CBC(Key, IV).Encrypt(PKCS7(明文))
```
关键陷阱：**salt 不是固定字符串，而是文件自身的 IV**。因此每个存档文件的密钥都不同，
用「固定 salt」去派生永远解不开——这是网上许多 ES3 示例与真实游戏实现之间最大的差异。
破解流程：
1. 读取存档 → 解析头部（大小、IV、是否像加密数据）；
2. 从游戏目录构建候选密码集合（DLL 字面量 + .assets 字符串 + 内置字典）；
3. 对每个候选密码执行 `解密 → PKCS7 校验 → 明文可读性 / ES3 标记检测`；
4. 通过校验且置信度最高的密码即为结果。
## 环境要求
| 组件 | 说明 |
|------|------|
| Python | 3.8+（推荐 3.11+） |
| 操作系统 | Windows（dnlib 通过 PowerShell 桥接调用；非 Windows 时自动回退为字节扫描，仅损失 DLL 字面量提取） |
| `pycryptodome` | 已随项目打包在 `libs/pycryptodome/`，无需手动安装 |
| `dnlib.dll` | 已随项目打包在 `libs/dnlib.dll`（开源 .NET 程序集解析库） |
## 安装说明
本项目为**免安装**结构，依赖已内置：
```
git clone <本仓库地址>
cd unity-es3-cracker
# 直接运行（依赖已在 libs/ 内）
python main.py
```
如果你的 Python 版本与内置 `pycryptodome` 不兼容（极少见），可手动重装：
```
pip install -r requirements.txt
```
## 使用方法
### 图形界面
```
python main.py
```
1. **游戏目录**：点击「浏览」选择游戏安装根目录（用于提取候选密码）。留空则仅使用内置常见密码。
2. **存档文件**：点击「选择」多选 `.es3` 文件（支持批量）。
3. 点击 **开始破解**，等待进度条与日志完成。
4. 结果区会列出每个存档**命中的密码**（按置信度排序），点击某条可在右侧查看**解密预览**。
5. 选中密码后点 **复制选中密码** 即可使用（例如配合 ES3 编辑器或自定义脚本修改存档）。
### 命令行模式
```
# 指定游戏目录 + 多个存档
python -m src.cli --game-dir "D:/Games/NTR Soccer" --saves save1.es3 save2.es3
# 仅用内置字典破解单个存档，并以 JSON 输出
python -m src.cli --saves save3.es3 --json
```
## 项目结构
```
unity-es3-cracker/
├── main.py # 程序入口（启动 GUI）
├── requirements.txt # Python 依赖
├── README.md
├── LICENSE
├── src/
│ ├── es3_crypto.py # ES3 AES 加解密 / 校验 / 头部解析
│ ├── candidates.py # 候选密码提取（dnlib + .assets + 内置字典）
│ ├── cracker.py # 破解编排（单文件 / 批量）
│ ├── gui.py # tkinter 图形界面
│ └── cli.py # 命令行界面
├── libs/
│ ├── dnlib.dll # 开源 .NET 程序集解析库（用于提取 DLL 字符串）
│ ├── extract_strings.ps1 # 调用 dnlib 的 PowerShell 桥接脚本
│ └── pycryptodome/ # 随附的 pycryptodome（Crypto 包）
└── docs/
├── USAGE.md # 详细使用指南
└── DEVELOPMENT.md # 开发与算法说明
```
## 依赖说明
- **dnlib**（MIT 许可证，）：通过 `libs/extract_strings.ps1`
在 PowerShell 中加载，提取游戏 DLL 的 C# 字符串字面量。Windows 专用；非 Windows 自动回退。
- **pycryptodome**（BSD 许可证，）：提供 AES / PBKDF2，
已打包在 `libs/pycryptodome/`，程序启动时自动加入 `sys.path`。
## 许可证
MIT —— 详见 [LICENSE](LICENSE)。
标签：AES, AI合规, DOS头擦除, Unity, 云资产清单, 安全助手, 密码破解, 逆向工具, 逆向工程