svn/upx-go

Public

WeChat Login

Code Issues Pull requests Events Packages Insights

master

Branch

Tag

山里人

refactor: rename upx proxy to upxg

1f8ddc75

8 commits

cmd
docs
internal
pkg
scripts
testdata
.gitignore
Makefile
README.md
go.mod
integration_matrix_test.go
integration_test.go
integration_upx_wrapper_test.go

UPX Obfuscator (Go)

UPX 文件检测、解析、混淆和还原工具集。面向 UPX 压缩后的可执行文件进行二次保护，增加静态分析难度，防止未授权解压和逆向分析。

功能特性

核心混淆技术

技术	优先级	说明	风险
魔数混淆	P0	修改 UPX! 签名	🟢 低
Overlay 注入	P0	追加混淆数据	🟢 低
头部字段伪造	P1	修改未使用字段	🟢 低
Hybrid/Decoy Overlay	P1	多模式混合注入	🟢 低
校验和破坏	P1	破坏校验字段	🔴 高
Stub 填充注入	P2	注入垃圾指令	🔴 高

RuntimeGuard 运行时保护

功能	说明
AES-256-GCM 分块加密	数据加密保护
RSA-OAEP 密钥封装	密钥安全分发
RSA-PSS-SHA256 签名	完整性验证
反调试检测	TracerPid 检测
禁用核心转储	防止内存泄露

Overlay 模式

模式	说明
`random`	加密安全随机字节
`junk_code`	x86 空操作指令（28 种模式）
`fake_strings`	伪造系统字符串（29 种）
`hybrid`	混合所有模式
`decoy_upx`	伪造 UPX 头结构

Profile 预设

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

基本使用

UPX 兼容代理（推荐入口）

./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 文件

# 混淆
./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 提高静态混淆强度。

RuntimeGuard（完整性 + 延迟解密链）

# 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> 导出运行时解密结果。

Profile 示例

# 平衡档（默认）
./upx-obfuscator --input sample.exe --profile balanced

# 隐蔽档（更小体积，偏向 decoy）
./upx-obfuscator --input sample.exe --profile stealth

# 激进档（更强混淆，体积增长更高）
./upx-obfuscator --input sample.exe --profile aggressive

Decoy 欺骗

# 自动按目标类型分流
./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

文档

API 文档 - 完整 API 参考
使用指南 - 详细使用说明
安全说明 - 合规与法律声明
设计文档 - 架构设计

项目结构

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/               # 构建脚本