
Devirtualizes Tencent VM .tvm0 sections: lifts VM handlers to guest-level listings and LLVM IR, recovers CFG and dispatch, and patches recovered code back into the PE.
Associated Zenodo record: 10.5281/zenodo.23474767.
⚠️ Disclaimer: This project is intended solely for authorized security research, interoperability analysis, and education, and does not contain or provide bypass functionality for commercial anti-cheat systems. Users must ensure they have the legal right to analyze the target binaries.
A virtualization recovery tool for Tencent VM. It recovers virtualized code from the .tvm0 section, extracts what each VM handler does to guest registers and memory, and can write the recovered functions back into the binary as a read-only executable section, thereby restoring the PE for easier reading.
.tvm0 段 -> VM 语义 -> guest 级 listing -> LLVM IR -> 打过补丁的 PE
The restored listing of a certain VM root, the form of the guest register set after cross-block binding.

The table below calculates the restoration ratio based on the number of functions that successfully generated machine code. All generated code passed comparison against the results of the project's interpreter.
| Component | Candidate Functions | Code Generated | Restoration Ratio |
|---|---|---|---|
ACE-ADVT.sys | 37 | 35 | 94.59% |
ACE-ADVT-1.0.2604.17113.sys | 37 | 34 | 91.89% |
ACE-BASE.sys | 274 | 254 | 92.70% |
ACE-BOOT.sys | 112 | 101 | 90.18% |
ACE-CORE.sys | 157 | 137 | 87.26% |
ACE-CORE.sys2 | 102 | 85 | 83.33% |
ACE-CORE.sys3 | 140 | 121 | 86.43% |
ACE-GAME.sys | 91 | 67 | 73.63% |
ACE-SSC-DRV64.sys | 192 | 162 | 84.38% |
The table below counts the number of recovered jumps found by the reference tool. It measures the degree of control flow coverage and is counted separately from the function restoration ratios in the table above.
| Component | Jump Restoration Ratio |
|---|---|
ACE-CORE.sys3 | 95.05% |
ACE-CORE.sys | 83.52% |
ACE-CORE.sys2 | 92.24% |
ACE-GAME.sys | 94.37% |
ACE-IDS64.dll | 91.43% |
ACE-CSI64.dll | 95.86% |
ACE-PBC-Game64.dll | 99.79% |
ACE-ATS64.dll | 94.03% |
ACE-BASE.sys | 96.46% |
SGuardAgent64.dll | 100.00% |
SGuard\x64\SGuard64.exe | 95.47% |
SGuard\x64\SGuardSvc64.exe | 100.00% |
SGuard\x64\SGuardUpdate64.exe | 100.00% |
SGuard\x64\ACE-Trace.dll | 0.00% |
ACE-Service64.exe | 100.00% |
python -m venv .venv
source .venv/Scripts/activate # Windows: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
Python 3.13, capstone. The backend additionally requires llvmlite==0.50.0, and on Windows it also requires MSVC link.exe/cl.exe. z3-solver is optional — without it, path conditionality still remains, only the bounded dispatch proof is skipped.
Copy .env.example to .env and fill in the local paths. .env is already gitignored; every configuration item also has a command-line argument, and the file only provides default values.
| Key | Meaning |
|---|---|
TVM_MODULE | Analysis target, used by probes without positional arguments |
TVM_LISTINGS | Listing directory read by the backend |
TVM_OUT | Root directory for all output (default out/) |
TVM_STEPS | Per-block step limit, truncated when reached (default 900000) |
TVM_BLOCKS | Per-root block budget (default 512) |
TVM_PAYLOAD_OPT | Payload codegen level 0–3 |
TVM_PAYLOAD_MEM | sealed | absolute guest memory mode |
TVM_MSVC_BIN | Directory containing link.exe/cl.exe, removing the dependency on PATH |
Priority: command-line arguments → .env → environment variables → built-in defaults.
Engine commands are run under engine/; backend commands are run from the repository root.
cd engine
python -m probe.scan_tvm0 /path/to/dir # 哪些文件带 .tvm0,以及它的 root
python -m probe.trampoline_forms input.exe # 入口跳板长什么样
python -m probe.mnemonic_census input.exe # VM 里包含哪些 x86
python -m core.devirt input.exe --out=../out/listings
Each function produces a 0x<root>.txt listing and a 0x<root>.guest-state.json. Options:
| Option | Default | Meaning |
|---|---|---|
--out=DIR | stdout | Write out the listing and guest state |
--root=0x… | all discovered | Process only one VM entry |
--show[=N] | off | Print the first N lines |
--steps=N | 900000 | Step limit per block; truncates when reached |
--blocks=N | 512 | Block budget per root |
--caller-entry=0x… --call-site=0x… | off | Apply caller specialization to the entry |
The header of each listing states whether this run was truncated; a truncated listing is a lower bound, not a complete function.
python -m probe.cfg_run input.exe 0x14015fc2e # 走一遍,打印 CFG
python -m probe.guest_effect input.exe 0x14015fc2e # handler 对 guest 寄存器的效果
python -m probe.ctx_map input.exe 0x14015fc2e # 哪个 context slot 存哪个 guest 寄存器
python -m probe.why_unresolved input.exe 0x14015fc2e # 某个 dispatch 为什么没解出
python -m probe.block_exits input.exe 0x14015fc2e # 某个块为什么没有后继
python -m probe.stop_debug input.exe 0x14015fc2e # 求值为什么停下
python -m probe.unresolved_detail input.exe 0x14015fc2e # 逐块细节
Trace to a specific value or a specific write:
python -m probe.trace_window input.exe 0x14015fc2e 0x14015fc40 0x14015fc90
python -m probe.reg_history input.exe 0x14015fc2e rax
python -m probe.who_wrote input.exe 0x14015fc2e 0x18
python -m probe.flags_at input.exe 0x14015fc2e 0x14015fc60
python -m probe.stack_at input.exe 0x14015fc2e
.\write-devirt.ps1 -Module 'C:\path\to\SGuardSvc64.exe'
Run payload → inject → load → diff in sequence, stopping at the first failure. Options: -Listings, -Out, -Opt 0..3, -Mem sealed|absolute, -SkipDifferential, -Force.
You can also run each stage individually:
cd llvm
python payload.py --listings=../out/hard-cases-listings-final --out=../out/write-devirt --opt=0 --mem=sealed
python peinject.py --host=input.exe --payload=../out/write-devirt --out=../out/write-devirt/input.neko.exe
python miniload.py ../out/write-devirt/input.neko.exe
python diff_payload.py --payload=../out/write-devirt --patched=../out/write-devirt/input.neko.exe
What is truly meaningful is diff_payload.py: it runs the code inside the patched image and compares it byte by byte with the interpreter on the same listing. miniload.py only proves that the image can load and that the entry point can run.
ACE 用一个跳板替换原生函数,跳入 VM dispatcher。dispatcher 执行的是原生 x86 handler,但被保护函数的体系结构状态存放在 VM context 中。
flowchart TB
subgraph TOP[ ]
direction LR
subgraph TEXT[.text]
ENTRY["<b>函数入口</b><br/>跳转到 VM entry"]
end
subgraph VM[.tvm0 段]
direction LR
CORE["<b>共享 dispatcher 与 handlers</b><br/>执行 x86 - 解析下一个 handler"]
CTX["<b>Guest context</b><br/>GPRs - RFLAGS - VIP"]
CORE <--> CTX
end
end