uksf/pbo-tool

# pbo-tool 忠实提取、编辑并重新打包**经过混淆的** Arma 3 PBO，这样就可以对 mod 进行补丁操作（如材质替换、微调），而无需将它们全部重新打包分发。普通的提取器在面对这种混淆时会出错，因为它会将非法字符（`*`、`?`、西里尔字节）塞入头文件名中；而此工具将这些名称视为不透明的 key，且从不对其进行解码，因此重新打包后的文件除了你编辑过的部分外，其余与原文件保持字节完全一致。 ## 用法 ``` python3 pbotool.py inspect # header + content-sniffed true type per entry python3 pbotool.py unpack # decompress to editable files + _manifest.json python3 pbotool.py repack [--source ] python3 pbotool.py sign --key [--keydir ] [--tooldir ] python3 pbotool.py verify --keydir [--tooldir ] ``` `sign`/`verify` 封装了官方的 BI Arma 3 Tools（DSCreateKey/DSSignFile/DSCheckSignatures）且仅在 Windows 上运行。`sign` 会复用 keydir（默认：pbo 所在文件夹）中已有的 `.biprivatekey`，或者创建一个新的，然后对该 pbo 进行签名。`verify` 会运行 `DSCheckSignatures -deep `，并为 checked_dir 中的每个 `.pbo` 输出一行 PASS/FAIL 结果。 `unpack` 会将每个文件以经过净化的文件名写出，并附带 `_manifest.json`（这是精确的重新打包蓝图：原始名称字节、header 字段、源数据偏移量、哈希值、可疑标志）。真正的资源文件会与混淆诱饵文件分离；可疑条目（poison/decoy）会被放入 `files/_suspect/` 目录下。 `repack` 会根据 manifest 逐字重建 header，从源 PBO 中逐字节复制未更改的数据块，并仅重新输出已编辑的文件（作为未压缩/stored 状态）。如果源 PBO 路径发生了移动，可以使用 `--source` 进行覆盖指定。 ## 混淆原理 仅 Header 攻击（较旧的 Mikero 时代，`DePbo.dll` 5.73-8.10）：诱饵条目（`\t\t`、`*.*`），使用西里尔 UTF-8 + `*`/`?` 破坏的文件名，伪造的扩展名，以及压缩大小超过原始大小的 poison `Cprs` 条目。文件数据本身永远不会被加密。具体的机制说明请参见 Brain vault（`concepts/arma/pbo-obfuscation-cyrillic-mangle.md`）。 ## 测试样本 `specimens/`（已在 gitignore 中忽略）保存了从 UKSF 的 `@uksf_dependencies` mod 中提取的已混淆和干净的 PBO 文件。它们属于第三方 mod 内容，并未被提交到代码库中。可以针对它们运行 `python3 selfcheck.py` 来进行字节完全一致的往返测试与替换测试。 ## 状态 - 往返操作（unpack -> repack）字节完全一致，已通过所有样本验证。 - 材质替换往返成功（见 `proof/`）：将真实的材质解码为 PNG，重新着色、替换、重新打包，再重新提取后像素完全一致。 - 签名已在目标环境上验证：经过编辑的已混淆 PBO 使用新密钥进行了签名，并通过 `DSCheckSignatures -deep` 验证（且在遭遇篡改字节或使用错误密钥时被正确拒绝）。BI 的工具链能够妥善处理这些混淆过的文件名。 ## 限制 - 无 LZSS 压缩器：编辑过的文件在重新打包时将保持存储状态（有效，但体积会稍大）。 - 验证部分的 PAA 编解码器会跳过 LZO1x 压缩的 mips，并编码为一个极简的单 mip 替代品；此类 PAA 在游戏内的加载效果尚未得到确认。

标签：Arma 3, PBO打包, Python, 文件解析, 无后门, 游戏工具, 逆向工具