re-vtil

MCP server for VTIL-Core (Virtual-machine Translation Intermediate Language, MIT). The "lift, optimize, emit pseudo-C" trio for VM handler characterization.

Why

The other RE-AI MCP servers handle byte-level binary analysis (re-lief, re-rizin, re-triton). They tell you what a handler does in machine code, but not what it means in a higher-level IL.

re-vtil fills that gap. You give it a function's machine code, it lifts to VTIL's IL, you run optimization passes, and you get a pseudo-C reading. The use case is the encrypted-VM handler characterization in re-encrypted-vm-tamper — once you know which bytes are a handler, re-vtil tells you what those bytes mean.

Architecture

The Python MCP server is a thin wrapper around a C++ vtil-cli helper built by install.sh from the vendored VTIL-Core source tree:

Claude Code (MCP stdio)
  │
  ▼
re-vtil server (Python, this directory)
  │  subprocess.run(...)
  ▼
vtil-cli (C++ single binary, built from src/re_vtil/cpp/VtilCli/)
  │
  └─ VTIL-Core (vendored as a git submodule)

The subprocess boundary is intentional: VTIL is a heavy C++ library with no first-class Python bindings. Process isolation is robust; the Python server always loads in degraded mode if the C++ helper is missing.

Tools

Tool	What it does
check_vtil	Health check — return VTIL version + supported archs
lift_handler	Lift machine code (base64) at a given base address to VTIL IL
optimize	Run VTIL optimization passes (dead-store-elim, branch-folding, mem-dep)
emit_pseudo_c	Emit a C-like pseudocode reading of an IL tree

Install

./install.sh builds vtil-cli via cmake --build against the vendored VTIL-Core source tree, then copies the binary to servers/re-vtil/bin/.

To build standalone (requires VTIL-Core source + cmake):

cd servers/re-vtil/src/re_vtil/cpp/VtilCli
cmake -B build -S .
cmake --build build --config Release
cp build/vtil-cli ../../../../bin/

To run:

re-vtil                          # stdio transport (default for MCP)
python -m re_vtil                # equivalent

Requirements

• VTIL-Core source tree (vendored as a submodule under src/re_vtil/cpp/)
• CMake ≥ 3.16
• A C++20 compiler (gcc-10+, clang-12+, MSVC 2019+)
• capstone + z3 (the C++ helper links against the same deps as re-triton)

Degraded mode

If vtil-cli is not built, every tool returns {"status": "WARN", "error": "vtil-cli not built; run install.sh", ...}. The Python MCP server itself always loads so Claude Code can surface the install hint.

Pairing with re-triton

re-triton handles concrete + symbolic execution (Triton lifts to its own AST, evaluates with a concrete or symbolic state). re-vtil handles static IL (VTIL lifts to its own IL, runs IR-level optimization, emits pseudo-C). The two are complementary:

• Use re-triton.solve_constraint for "what input reaches this branch?"
• Use re-vtil.lift_handler + optimize + emit_pseudo_c for "what does this handler do in the abstract?"

For the encrypted-VM bytecode family: re-triton.emulate_function runs the encrypted handler under concrete inputs (decryption stub triggers, handler dispatches); re-vtil.lift_handler lifts the decrypted handler body to VTIL IL for the static read.