UPX 文件检测、解析、混淆和还原工具集。面向 UPX 压缩后的可执行文件进行二次保护，增加静态分析难度，防止未授权解压和逆向分析。
| 技术 | 优先级 | 说明 | 风险 |
|---|---|---|---|
| 魔数混淆 | P0 | 修改 UPX! 签名 | 🟢 低 |
| Overlay 注入 | P0 | 追加混淆数据 | 🟢 低 |
| 头部字段伪造 | P1 | 修改未使用字段 | 🟢 低 |
| Hybrid/Decoy Overlay | P1 | 多模式混合注入 | 🟢 低 |
| 校验和破坏 | P1 | 破坏校验字段 | 🔴 高 |
| Stub 填充注入 | P2 | 注入垃圾指令 | 🔴 高 |
| 功能 | 说明 |
|---|---|
| AES-256-GCM 分块加密 | 数据加密保护 |
| RSA-OAEP 密钥封装 | 密钥安全分发 |
| RSA-PSS-SHA256 签名 | 完整性验证 |
| 反调试检测 | TracerPid 检测 |
| 禁用核心转储 | 防止内存泄露 |
| 模式 | 说明 |
|---|---|
random | 加密安全随机字节 |
junk_code | x86 空操作指令（28 种模式） |
fake_strings | 伪造系统字符串（29 种） |
hybrid | 混合所有模式 |
decoy_upx | 伪造 UPX 头结构 |
| Profile | Overlay | Jitter | Ratio | Layers | 适用场景 |
|---|---|---|---|---|---|
balanced | 4KB | 12% | 20% | 2 | 通用场景 |
stealth | 2KB | 6% | 12% | 4 | 高隐蔽需求 |
aggressive | 8KB | 25% | 35% | 6 | 最强混淆 |
cd /workspace
make build
生成文件（在当前目录）：
upxg- UPX 兼容代理：先调用原版 UPX，再执行二次混淆upx-obfuscator- 混淆工具upx-restore- 还原工具upx-keygen- RuntimeGuard 密钥生成upx-seal- RuntimeGuard 封装upx-launch- RuntimeGuard 运行/导出
提示：若需输出到
bin/目录，可执行mkdir -p bin && go build -o bin/ ./cmd/...
也可以单独安装推荐入口，名称使用 upxg（UPX Guard），避免 go install 后与原版 upx 同名抢占 PATH：
go install cnb.cool/svn/upx-go/cmd/upxg@latest
./upxg 接收原版 UPX 参数并原样透传；真实 UPX 压缩成功后，对 UPX 产物执行当前项目的默认混淆链并生成 <target>.key.json。
# 行为等价于：upx --force -1 sample.exe；随后自动混淆 sample.exe
./upxg --upx-bin /usr/bin/upx --force -1 sample.exe
# 保持 UPX 的 -o/--output= 输出语义，混淆目标为 packed.exe
./upxg --upx-bin /usr/bin/upx --force -9 -o packed.exe sample.exe
./upxg --upx-bin /usr/bin/upx --force -9 --output=packed.exe sample.exe
# 一键方案：自动注入常用 UPX 压缩参数，并匹配混淆 profile
./upxg --upx-bin /usr/bin/upx --pack-profile=fast sample.exe
./upxg --upx-bin /usr/bin/upx --pack-profile=stealth -o packed.exe sample.exe
说明：
- 原版 UPX 位置可通过
--upx-bin <path>或环境变量UPX_REAL_BIN指定。 -d、-l、-t、--decompress、--uncompress、--list、--test、--fileinfo、help/version/license 等非压缩流程只透传真实 UPX，不执行混淆。- 需要调整混淆策略时使用
--obf-*前缀，例如--obf-profile=stealth、--obf-generate-key=false；这些参数不会传给真实 UPX。 --pack-profile内置fast、balanced、best、lzma、stealth、brute、ultra，用于一键压缩并混淆；显式 UPX 参数仍会保留在后方，便于覆盖细节。
# 混淆
./upx-obfuscator --input sample.exe --output sample.exe.obf
# 简洁模式：自动备份原文件，并输出去掉 .upx 后缀的新可执行文件
./upx-obfuscator sample.exe.upx
# 还原
./upx-restore --input sample.exe.obf --key sample.exe.obf.key.json --output sample.exe.restored
# 验证
sha256sum sample.exe sample.exe.restored
说明：
- CLI 默认优先保证混淆产物可直接执行，因此默认不启用头部伪造（
--spoof-header=false）。 - 若产物主要用于离线存储、配合
upx-restore或upx-launch --restore-key使用，可显式启用--spoof-header=true提高静态混淆强度。
# 1) 生成密钥（签名/解封）
./upx-keygen --output-dir keys --prefix guard --bits 3072
# 2) 对混淆产物进行封装（签名 + 分块加密）
./upx-seal \
--input sample.exe.obf \
--output sample.exe.obf.rgpkg \
--sign-priv keys/guard.sign.private.pem \
--wrap-pub keys/guard.wrap.public.pem \
--deny-debugger true \
--disable-core-dump true
# 3) 运行时校验 + 解密 + （可选）还原补丁 + 执行
./upx-launch \
--input sample.exe.obf.rgpkg \
--verify-pub keys/guard.sign.public.pem \
--unwrap-priv keys/guard.wrap.private.pem \
--restore-key sample.exe.obf.key.json
说明：
--restore-key为可选参数，用于把加花后的 payload 恢复为可执行态再启动。- 不执行时可用
--extract <path>导出运行时解密结果。
# 平衡档（默认）
./upx-obfuscator --input sample.exe --profile balanced
# 隐蔽档（更小体积，偏向 decoy）
./upx-obfuscator --input sample.exe --profile stealth
# 激进档（更强混淆，体积增长更高）
./upx-obfuscator --input sample.exe --profile aggressive
# 自动按目标类型分流
./upx-obfuscator --input sample.exe \
--overlay-pattern decoy_upx \
--decoy-format auto \
--decoy-layers 4
# 指定目标格式
./upx-obfuscator --input sample.exe \
--overlay-pattern decoy_upx \
--decoy-format pe \
--decoy-layers 6
默认启用 SafeMode，自动禁用高风险操作：
# 安全模式（默认）
./upx-obfuscator --input sample.exe --safe-mode
# 禁用安全模式（谨慎使用）
./upx-obfuscator --input sample.exe \
--safe-mode false \
--disrupt-checksum true
警告：高风险操作可能导致程序无法运行！
混淆时自动生成还原密钥（JSON 格式），包含所有修改的字节级补丁记录：
{
"records": [
{
"offset": 236,
"length": 4,
"original_hex": "55585021",
"description": "packheader magic"
}
]
}
安全建议：
- 妥善保管还原密钥
- 设置限制性权限：
chmod 600 *.key.json
# 单元测试
make test
# 端到端测试
make e2e
# 双版本 UPX 兼容性回归（系统 upx + 当前项目 ./upxg 代理）
make compat
# 系统 UPX + GitHub 最新源码编译版 UPX 的代理矩阵回归
make compat-latest
# 双版本 UPX + spoof-header 直接执行回归（系统 upx + 官方 upx）
make obf-compat
# 生成测试样本
make samples
upx/
├── cmd/
│ ├── upxg/ # UPX 兼容代理入口
│ ├── upx-obfuscator/ # 混淆工具入口
│ ├── upx-restore/ # 还原工具入口
│ ├── upx-keygen/ # RuntimeGuard 密钥生成
│ ├── upx-seal/ # RuntimeGuard 封装
│ └── upx-launch/ # RuntimeGuard 运行器
├── internal/
│ ├── app/ # 可复用应用服务（混淆/还原）
│ ├── cliutil/ # CLI 文件写入与权限工具
│ ├── format/ # UPX 格式定义
│ ├── patch/ # 补丁记录系统
│ └── upxproxy/ # 原版 UPX 代理与参数编排
├── pkg/
│ ├── detector/ # UPX 检测
│ ├── obfuscator/ # 混淆引擎
│ ├── parser/ # 文件解析
│ ├── runtimeguard/ # 运行时完整性与延迟解密
│ ├── utils/ # 工具函数
│ └── writer/ # 文件写入
├── docs/ # 文档
├── testdata/ # 测试数据
└── scripts/ # 构建脚本
- 合法使用：本工具仅用于防御性安全和授权测试
- 安全模式：默认启用，禁用高风险操作
- 备份原始：混淆前请保留原始文件备份
- 保管密钥：还原密钥可完全还原文件，需妥善保管
本工具仅供合法授权使用。详见 安全说明。
35/F,Tencent Building,Kejizhongyi Avenue,Nanshan District,Shenzhen
