ykus4/kagura
GitHub: ykus4/kagura
基于 LLVM New Pass Manager 的原生代码混淆插件，提供控制流混淆、字符串加密、反调试、VM 虚拟化等多层保护，支持 iOS 与 Android 平台且无需修改 LLVM 源码。
Stars: 1 | Forks: 0
# Kagura
基于 **New Pass Manager** (LLVM 17+) 构建。通过 `-fpass-plugin` 作为 pass 插件加载——无需修改 LLVM 源码树。
## 架构
```
kagura/
├── include/kagura/ # Public headers (Passes.h, Options.h, Utils.h, game_protect.h)
├── lib/Transforms/
│ ├── CFG/ # Control-flow obfuscation passes
│ ├── Data/ # String/constant/global/wide-string/memory-value encryption
│ ├── AntiAnalysis/ # Anti-debug, integrity, call indirection, honey values
│ ├── Platform/ # iOS (ObjC), Android (JNI), VM virtualization
│ ├── Infrastructure/ # DWARF control, config DSL, symbol map
│ ├── Options.cpp # Centralized CLI flag definitions
│ ├── Plugin.cpp # Pass registration & pipeline wiring
│ └── Utils.cpp # Shared IR helpers & PRNG
├── runtime/
│ ├── core/ # AES, VM interpreter, crash symbolication, device key
│ ├── anti_debug/ # Anti-debug / anti-Frida (cross-platform)
│ ├── android/ # Android + Linux: root detection, attestation, proc/syscall
│ ├── ios/ # iOS / macOS: jailbreak detection, Mach-O integrity
│ └── game/ # Anti-cheat, IL2CPP protection, telemetry
├── integration/ # Xcode, Gradle, Unity, Unreal, CMake, Bazel, CocoaPods, SPM
├── scripts/ # CLI tools, verification, differential testing, review risk assessment
└── tests/ # CTest + FileCheck lit-based regression tests
```
## Pass 列表
### 控制流 (`CFG/`)
| 标志 | Pass | 效果 |
|:-----|:-----|:-------|
| `-kagura-fla` | ControlFlowFlattening | 将 CFG 转换为基于 switch 的状态机 |
| `-kagura-bcf` | BogusControlFlow | 注入由 MBA 不透明谓词保护的虚假块 |
| `-kagura-ibr` | IndirectBranch | 将直接调用替换为从函数指针全局变量加载的形式 |
| `-kagura-ci` | CallIndirection | 通过运行时解析的 thunk 表路由外部调用 |
| `-kagura-lt` | LoopTransform | 添加虚假的死计数器和不透明的不变分支 |
| `-kagura-fsplit` | FunctionSplit | 将内部基本块提取为外联的辅助函数 |
| `-kagura-bbs` | BasicBlockSplitting | 在随机点拆分大型 BB 以增加 CFG 的复杂性 |
| `-kagura-bbr` | BasicBlockReordering | 打乱 BB 布局以干扰线性反汇编器 |
| `-kagura-dci` | DeadCodeInsertion | 插入不可达的垃圾块以误导静态分析 |
| `-kagura-elt` | EncryptedLookupTable | 将 switch 语句转换为 XOR 加密的调度表 |
| `-kagura-vtp` | VTableProtection | 混淆 C++ RTTI typeinfo 名称 (`_ZTS*`)；记录 vtable 元数据 |
### 数据混淆 (`Data/`)
| 标志 | Pass | 效果 |
|:-----|:-----|:-------|
| `-kagura-str` | StringEncryption | 对窄字符串字面量进行 XOR 加密；首次访问时延迟解密 |
| `-kagura-str-aes` | StringEncryptionAES | AES-128-CTR 字符串加密（需要运行时） |
| `-kagura-wstr` | WideStringEncryption | 对宽字符串 (wchar_t / char16_t / char32_t) 和 CFString 缓冲区进行 XOR 加密 |
| `-kagura-co` | ConstantObfuscation | 将整数常量替换为 MBA 表达式 |
| `-kagura-sub` | Substitution | 将算术/位运算替换为等价的 MBA |
| `-kagura-genc` | GlobalEncryption | 加密私有的整数全局变量；在加载位置内联 XOR |
| `-kagura-mvo` | MemoryValueObfuscation | 在每个 store/load 位置对 alloca 分配的整数局部变量进行 XOR 加密 |
| `-kagura-pe` | PointerEncryption | 对 alloca 分配的指针变量进行 XOR 加密，以对抗内存转储分析 |
### 反分析 (`AntiAnalysis/`)
| 标志 | Pass | 效果 |
|:-----|:-----|:-------|
| `-kagura-anti-debug` | AntiDebug | ptrace、Frida 端口、`/proc/maps`、hook、断点、模拟器检测 |
| `-kagura-tamper` | AntiTamper | 启动时的 FNV-1a 函数校验和 + 越狱/root 检测 |
| `-kagura-pac` | PointerAuth | 通过 XOR 标记的函数指针全局变量实现软件 CFI |
| `-kagura-sv` | SymbolVisibility | 将非公开符号设置为 hidden；从动态符号表中剥离 |
| `-kagura-honey` | HoneyValue | 注入诱饵秘密全局变量和虚假的 security-stub 函数 |
| `-kagura-bbcheck` | BasicBlockChecksum | 注入每个 BB 的操作码校验和；在检测到二进制补丁时中止 |
| `-kagura-telemetry` | Telemetry | 在函数入口处插入行为事件探针，用于作弊检测 |
### 特定平台 (`Platform/`)
| 标志 | Pass | 目标平台 |
|:-----|:-----|:-------|
| `-kagura-objc` | ObjCObfuscation | iOS — 混淆 IR 元数据中的 ObjC selector 和类名 |
| `-kagura-jni` | JNIObfuscation | Android — 将静态 `Java_*` 转换为动态 `RegisterNatives` |
| `-kagura-vm` | VMObfuscation | 将函数体虚拟化为自定义的基于栈的 VM 字节码 |
### 基础设施 (`Infrastructure/`)
| 标志 | Pass | 效果 |
|:-----|:-----|:-------|
| `-kagura-dwarf=strip\|obfuscate` | DWARFControl | 在混淆后剥离或重映射 DWARF 调试信息 |
| `-kagura-config=
` | ConfigLoader | 加载 JSON 策略文件；应用配置文件预设和逐 pass 覆盖 |
| `-kagura-symmap` | SymbolMap | 生成 JSON 符号映射（原始名称 → 混淆后名称）用于崩溃符号化还原 |
| `-kagura-audit` | AuditLog | 生成 JSON 审计日志，记录每个受保护的符号和应用的 pass |
### 实用工具
| 标志 | Pass | 效果 |
|:-----|:-----|:-------|
| `-kagura-metrics` | ObfuscationMetrics | 打印 BB/指令/圈复杂度的变化量 |
## 调优参数
| 选项 | 默认值 | 描述 |
|:-------|:--------|:------------|
| `-kagura-seed=` | `0` (熵) | 用于可重现输出的 PRNG 种子 |
| `-kagura-bcf-prob=` | `30` | 每个 BB 的虚假 CF 概率 [0-100] |
| `-kagura-bcf-iter=` | `1` | 虚假 CF 迭代次数 |
| `-kagura-sub-iter=` | `1` | 替换迭代次数 |
| `-kagura-dci-prob=` | `40` | 死代码插入概率 [0-100] |
### 基础设施选项
| 选项 | 默认值 | 描述 |
|:-------|:--------|:------------|
| `-kagura-lto-safe` | `false` | 在 LTO/ThinLTO 管道阶段启用 pass |
| `-kagura-o0-protect` | `false` | 在 `-O0` 启用轻量级保护 (STR, AntiDebug) |
| `-kagura-dwarf=` | `keep` | DWARF 处理方式：`keep` / `strip` / `obfuscate` |
| `-kagura-build-id=` | — | 混入 PRNG 种子的构建标识符，用于每次构建的密钥轮换 |
### 构建系统选项
| 选项 | 默认值 | 描述 |
|:-------|:--------|:------------|
| `-kagura-config=` | — | JSON 策略文件的路径 |
| `-kagura-symmap` | `false` | 在混淆后生成符号映射 |
| `-kagura-symmap-out=` | `kagura_symbols.json` | 符号映射的输出文件 |
| `-kagura-audit` | `false` | 生成所有受保护符号的审计日志 |
| `-kagura-audit-out=` | `kagura_audit.json` | 审计日志的输出文件 |
### 符号过滤选项
| 选项 | 默认值 | 描述 |
|:-------|:--------|:------------|
| `-kagura-protect=` | — | 强制保护匹配的符号（逗号分隔，支持 `*` 通配符） |
| `-kagura-deny=` | — | 从所有混淆中排除匹配的符号 |
| `-kagura-allow=` | — | 允许列表模式：仅混淆匹配的符号 |
## Config DSL 与强度配置
Kagura 支持 JSON 策略文件 (`-kagura-config=`) 来集中控制所有的 pass 设置。
```
{
"profile": "BALANCED",
"passes": {
"str": true,
"fla": true,
"bcf": true,
"honey": true,
"mvo": false
},
"tuning": {
"bcf_prob": 40,
"seed": 12345
}
}
```
**内置配置：**
| 配置 | Pass | 预期用途 |
|:--------|:-------|:-------------|
| `FAST` | 仅 STR | 具有最小开销的 Debug/CI 构建 |
| `BALANCED` | STR + BCF + BBR + BBS + GENC + MVO | 标准 Release 构建 |
| `STRONG` | 所有 pass，BCF 概率 60，2 次迭代 | 安全关键型的发布构建 |
## 游戏保护
`include/kagura/game_protect.h` 提供了一个仅包含头文件的 C++17 `Protected` 模板，用于保护游戏关键数值（HP、伤害、货币等）免受内存扫描器和冻结工具的篡改。
```
#include "kagura/game_protect.h"
kagura::Protected hp(100);
kagura::Protected speed(5.5f);
hp -= 30;
if (hp <= 0) die();
// Optional tamper callback (default: spin forever to deny clean crash point)
kagura::Protected::setTamperCallback([]{ report_cheat(); });
```
**保护策略：**
- 值使用实例级运行时密钥（ASLR + 栈熵）进行 XOR 加密存储
- 影子副本（使用不同的 XOR 掩码）实现外部写入检测
- 纯文本值在读写之间不会驻留在内存中
便捷别名：`ProtectedInt`、`ProtectedFloat`、`ProtectedDouble`、`ProtectedInt64` 等。
## 系统要求
- **LLVM 17 – 22**（在 17、18、19、21、22 上测试）
- CMake 3.20+
- C++17
## 快速入门
### 下载预构建版本
预构建的插件二进制文件已在 [GitHub Releases 页面](../../releases) 随每个版本发布。
```
kagura--macos-arm64-llvm21.tar.gz
kagura--macos-arm64-llvm22.tar.gz
kagura--linux-x86_64-llvm19.tar.gz
kagura--linux-x86_64-llvm21.tar.gz
kagura--linux-x86_64-llvm22.tar.gz
```
每个压缩包包含：
- `plugin/KaguraObfuscator.{dylib,so}`
- `runtime/libkagura_runtime.a`
- `include/kagura/*.h`
### 从源码构建
```
# macOS (Homebrew LLVM)
brew install llvm
bash build.sh
# 自定义 LLVM
cmake -B build \
-DLLVM_DIR=/path/to/llvm/lib/cmake/llvm \
-DCMAKE_C_COMPILER=/path/to/clang \
-DCMAKE_CXX_COMPILER=/path/to/clang++ \
.
cmake --build build -j$(nproc)
```
输出：`build/lib/Transforms/KaguraObfuscator.dylib` (或在 Linux 上为 `.so`)。
### 结合 clang 使用
```
clang -fpass-plugin=build/lib/Transforms/KaguraObfuscator.dylib \
-mllvm -kagura-str \
-mllvm -kagura-fla \
-mllvm -kagura-bcf \
-mllvm -kagura-bcf-prob=50 \
-O1 your_file.c -o your_file
```
### 结合 JSON 配置使用 (推荐用于项目)
```
clang -fpass-plugin=build/lib/Transforms/KaguraObfuscator.dylib \
-mllvm -kagura-config=kagura.json \
-O1 your_file.c -o your_file
```
### 结合 opt 使用 (IR 级别)
```
clang -O1 -emit-llvm -c your_file.c -o your_file.bc
opt --load-pass-plugin=build/lib/Transforms/KaguraObfuscator.dylib \
-passes="kagura-str,function(kagura-fla,kagura-bcf,kagura-sub)" \
your_file.bc -o your_file.opt.bc
clang your_file.opt.bc -o your_file
```
### 逐函数控制 (注解)
```
// Force-enable a pass for this function
__attribute__((annotate("kagura_fla")))
void critical_function(void) { ... }
// Force-disable a pass for this function
__attribute__((annotate("kagura_nofla")))
void performance_sensitive(void) { ... }
// Virtualize with the VM pass
__attribute__((annotate("kagura_vm")))
int verify_license(const char *key) { ... }
```
## 推荐的 Pass 顺序
插件通过 `registerOptimizerLastEPCallback` 自动应用此顺序：
```
-O1 / -O2 (standard optimizations first)
1. kagura-config → load JSON policy (if -kagura-config is set)
2. kagura-ci → external call indirection
3. kagura-pac → pointer auth
4. kagura-str[-aes] → encrypt narrow strings
5. kagura-wstr → encrypt wide strings / CFString
6. kagura-tamper → integrity hash (before CFG changes)
7. kagura-objc → ObjC selector/class obfuscation
8. kagura-jni → JNI dynamic registration
9. kagura-anti-debug → anti-analysis checks
10. kagura-fsplit → function splitting
11. kagura-genc → encrypt globals
12. kagura-honey → inject honey values and fake stubs
13. kagura-sv → hide symbols
14. kagura-fla → CFG flattening ┐
15. kagura-bcf → bogus control flow │
16. kagura-bbs → BB splitting │
17. kagura-bbr → BB reordering │
18. kagura-dci → dead code insertion │
19. kagura-sub → instruction subst. │ function passes
20. kagura-co → constant obfuscation │
21. kagura-mvo → memory value XOR │
22. kagura-pe → pointer encryption │
23. kagura-telemetry → telemetry probes │
24. kagura-bbcheck → BB checksum guards │
25. kagura-elt → encrypted lookup tbl ┘
26. kagura-dwarf-control → DWARF strip/obfuscate (if -kagura-dwarf != keep)
27. kagura-vtp → RTTI/vtable protection
28. kagura-symmap → emit JSON symbol map (if -kagura-symmap)
29. kagura-audit → emit audit log (if -kagura-audit)
```
## 运行时库
某些 pass 需要链接 `libkagura_runtime.a`：
| Pass | 所需符号 |
|:-----|:-----------------|
| StringEncryptionAES | `kagura_aes128_ctr_decrypt` |
| VMObfuscation | `kagura_vm_execute` |
| AntiDebug | `kagura_anti_debug_init`, `kagura_check_hooks`, `kagura_check_breakpoints`, `kagura_check_emulator` |
| AntiTamper | `kagura_self_check`, `kagura_tamper_detected` |
| CallIndirection | `dlsym` (系统) |
| PointerAuth | `kagura_random_u64` |
| StringEncryptionAES | `kagura_zero_buf` |
```
clang your_file.c build/runtime/libkagura_runtime.a -o your_file
```
运行时还提供了可直接调用的防篡改检查：
```
#include "kagura/runtime.h"
kagura_self_check(); // Mach-O / ELF integrity + jailbreak/root
kagura_check_loaded_libraries(); // Suspicious dylib/so scan
kagura_run_review_risk_check(); // App Store / Play Store pre-submission scan
```
## 集成
| 平台 | 快速设置 | 指南 |
|:---------|:------------|:------|
| **Xcode** | 添加 `integration/xcode/kagura.xcconfig` + run script 阶段 | [Xcode 集成指南](integration/xcode/README.md) |
| **Android (Gradle / NDK)** | `apply from: "kagura/integration/android/kagura.gradle"` | [Android NDK 集成指南](integration/android/README.md) |
| **Unity (IL2CPP)** | 复制 `Editor/KaguraPostBuildProcessor.cs` 到 `Assets/Editor/` | [Unity 集成指南](integration/unity/README.md) |
| **Unreal Engine 5** | 复制 `KaguraToolchain.cs` 到 UBT toolchain 路径 | [Unreal Engine 集成指南](integration/unreal/README.md) |
| **CMake (Cocos2d-x 等)** | `-DCMAKE_TOOLCHAIN_FILE=kagura-toolchain.cmake` | [Android NDK 集成指南](integration/android/README.md) |
| **Bazel** | `load("@kagura//integration/bazel:kagura.bzl", "kagura_cc_binary")` | [Bazel 集成指南](integration/bazel/README.md) |
| **CocoaPods** | `pod 'KaguraRuntime'` + 用于 plugin 标志的 xcconfig | [CocoaPods 集成指南](integration/cocoapods/README.md) |
| **Swift Package Manager** `.product(name: "KaguraRuntime", package: "kagura")` | [SPM 集成指南](integration/swiftpm/README.md) |
## 测试
```
cd build && ctest --output-on-failure
```
### 可重现构建验证
验证固定种子在两次构建中是否生成字节完全相同的 IR：
```
./scripts/verify-reproducible.sh
# [kagura-repro] 通过：两次构建生成了相同的 IR。
```
### 差异测试
验证混淆后的二进制文件是否产生与原始二进制文件相同的输出：
```
./scripts/differential-test.sh
# [diff-test] arithmetic_test ... 通过
# [diff-test] combined_test ... 通过
# 结果：8 个通过，0 个失败，0 个跳过
```
### App Store / Google Play 审核风险评估
扫描已编译的二进制文件，查找可能触发商店审核拒绝的模式：
```
./scripts/review-risk-assessment.sh path/to/MyApp.dylib --platform ios
# [HIGH ] [SEC-PIE] ...
# [INFO ] [ENC-DECL] 未发现明显的加密关键字引用。
# 结果：未检测到严重或高级别的审查风险。
```
### 其他工具
| 脚本 | 用途 |
|:-------|:--------|
| `scripts/kagura-cli.py` | 配置生成器、审计日志查看器、符号映射分析器 |
| `scripts/variant_generator.py` | 使用自定义密钥按客户/按应用生成变体 |
| `scripts/attacker_cost_model.py` | 估算攻击者逆向工程成本 (分析师工时) |
| `scripts/battery_impact.py` | 模拟运行时 pass 对电池 / CPU 的影响 |
| `scripts/license_manager.py` | 生成、验证和撤销有时限的许可证令牌 |
### 安全性评估
```
# Symbolic execution 抵抗力
cd tests/symbolic_exec && python3 run_angr_eval.py --binary /tmp/my_binary --timeout 30
# Decompiler 抵抗力
cd tests/decompiler_eval && python3 run_ghidra_eval.py --binary /tmp/my_binary --ghidra /path/to/ghidra
# Frida instrumentation 抵抗力 (probes F1-F8)
cd tests/frida_resistance && for s in probes/F*.js; do frida -l "$s" -f /tmp/my_binary; done
# 完整的红队报告
cd tests/redteam && python3 run_redteam.py --binary /tmp/my_binary --report report.json
```
## 许可证
MIT — 详见 [LICENSE](LICENSE)。标签：Android, Bash脚本, C++17, DOM解析, DSL, GitHub Advanced Security, HTTP头分析, iOS, LLVM, LLVM Pass, Native, New Pass Manager, VM虚拟化, XML 请求, 云资产清单, 代码保护, 代码混淆, 反调试, 字符串加密, 安全加固, 安全开发, 完整性校验, 抗分析, 控制流平坦化, 游戏保护, 目录枚举, 移动安全, 编译器插件, 虚拟机保护, 逆向工程, 静态分析防御, 黑盒防护