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/upx
make build

生成文件（在当前目录）：

• upx-obfuscator - 混淆工具
• upx-restore - 还原工具
• upx-keygen - RuntimeGuard 密钥生成
• upx-seal - RuntimeGuard 封装
• upx-launch - RuntimeGuard 运行/导出

提示：若需输出到 bin/ 目录，可执行 mkdir -p bin && go build -o bin/ ./cmd/...

# 混淆
./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 + /workspace/bin/upx）
make compat

# 双版本 UPX + spoof-header 直接执行回归（系统 upx + 官方 upx）
make obf-compat

# 生成测试样本
make samples

---

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

---

upx/
├── cmd/
│   ├── upx-obfuscator/    # 混淆工具入口
│   ├── upx-restore/       # 还原工具入口
│   ├── upx-keygen/        # RuntimeGuard 密钥生成
│   ├── upx-seal/          # RuntimeGuard 封装
│   └── upx-launch/        # RuntimeGuard 运行器
├── internal/
│   ├── format/            # UPX 格式定义
│   └── patch/             # 补丁记录系统
├── pkg/
│   ├── detector/          # UPX 检测
│   ├── obfuscator/        # 混淆引擎
│   ├── parser/            # 文件解析
│   ├── runtimeguard/      # 运行时完整性与延迟解密
│   ├── utils/             # 工具函数
│   └── writer/            # 文件写入
├── docs/                  # 文档
├── testdata/              # 测试数据
└── scripts/               # 构建脚本

---

1. 合法使用：本工具仅用于防御性安全和授权测试
2. 安全模式：默认启用，禁用高风险操作
3. 备份原始：混淆前请保留原始文件备份
4. 保管密钥：还原密钥可完全还原文件，需妥善保管

---

本工具仅供合法授权使用。详见 安全说明。