Skip to content
KitploitKITPLOIT
ToolsExploitsBlog
Log in
Submit
ToolsExploitsBlog
Submit

Hacking, PenTest, and Cybersecurity Tools for Your Security Arsenal!

Kitploit is a directory of hacking, cybersecurity, and pentesting tools. Discover the latest project updates to find vulnerabilities, analyze systems, automate testing, and strengthen your security.

FeedsContactPrivacy© 2026 Kitploit

Tool Directory

Categories

View all categories
Loading categories
tvm-recover — 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. | Kitploit
Tools/GitHubGitHub/neurosaki987/tvm-recover
Static AnalysisCode AnalysisDynamic Code Analysis (DAST)Reverse EngineeringDebuggersBinary AnalysisPapers & ResearchBinary Exploitation
GitHubneurosaki987/tvm-recover

tvm-recover

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.

8122844 days agoReviewed by Kitploit
View Repository
Share

中文  English

tvm-recover

DOI

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.

Virtualization restoration effect diagram

Restoration Results by Component

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.

ComponentCandidate FunctionsCode GeneratedRestoration Ratio
ACE-ADVT.sys373594.59%
ACE-ADVT-1.0.2604.17113.sys373491.89%
ACE-BASE.sys27425492.70%
ACE-BOOT.sys11210190.18%
ACE-CORE.sys15713787.26%
ACE-CORE.sys21028583.33%
ACE-CORE.sys314012186.43%
ACE-GAME.sys916773.63%
ACE-SSC-DRV64.sys19216284.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.

ComponentJump Restoration Ratio
ACE-CORE.sys395.05%
ACE-CORE.sys83.52%
ACE-CORE.sys292.24%
ACE-GAME.sys94.37%
ACE-IDS64.dll91.43%
ACE-CSI64.dll95.86%
ACE-PBC-Game64.dll99.79%
ACE-ATS64.dll94.03%
ACE-BASE.sys96.46%
SGuardAgent64.dll100.00%
SGuard\x64\SGuard64.exe95.47%
SGuard\x64\SGuardSvc64.exe100.00%
SGuard\x64\SGuardUpdate64.exe100.00%
SGuard\x64\ACE-Trace.dll0.00%
ACE-Service64.exe100.00%

Build

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.

Configuration

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.

KeyMeaning
TVM_MODULEAnalysis target, used by probes without positional arguments
TVM_LISTINGSListing directory read by the backend
TVM_OUTRoot directory for all output (default out/)
TVM_STEPSPer-block step limit, truncated when reached (default 900000)
TVM_BLOCKSPer-root block budget (default 512)
TVM_PAYLOAD_OPTPayload codegen level 0–3
TVM_PAYLOAD_MEMsealed | absolute guest memory mode
TVM_MSVC_BINDirectory containing link.exe/cl.exe, removing the dependency on PATH

Priority: command-line arguments → .env → environment variables → built-in defaults.

Usage

Engine commands are run under engine/; backend commands are run from the repository root.

Finding virtualization code

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

Restore

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:

OptionDefaultMeaning
--out=DIRstdoutWrite out the listing and guest state
--root=0x…all discoveredProcess only one VM entry
--show[=N]offPrint the first N lines
--steps=N900000Step limit per block; truncates when reached
--blocks=N512Block budget per root
--caller-entry=0x… --call-site=0x…offApply 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.

Understanding a single 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 back to binary

.\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.

How the VM works

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
Download Tool

Most Popular

View all →

Discover the most used tools by our community.

No popularity data yet.

Explore all tools

Browse our collection of tools

View all tools →