Skip to main content
Glama

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.

Related MCP server: GhidraMCP

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.

Available Tools

5 tools
check_vtilA

Return vtil-cli version + supported architectures.

Reports WARN (not ERROR) when the vtil-cli binary is not found — the Python server itself always loads. The fallback chain: $RE_VTIL_CLI_PATH -> <server>/bin/vtil-cli -> PATH.

Inputs: no named parameters.

emit_pseudo_cA

Emit a pseudo-C reading of a lifted IL tree.

The output is best-effort — VTIL's emulator walks the IL and produces a C-like pseudocode that an analyst can read. The quality is much lower than IDA Hex-Rays or Ghidra's decompiler; the use case is a quick first-pass read of a VM handler body, not a full decompilation.

Args: il: the IL tree (raw from lift_handler or optimized via :func:optimize)

Returns::

{"code": "C-like pseudocode...", "il_block_count": N}

Inputs: il (required).

lift_handlerA

Lift arch / code to VTIL intermediate language.

Args: arch: target architecture — one of x86, x86_64, aarch64, arm32 code: machine-code bytes, base64-encoded (base64 is transport-friendly; the CLI decodes back to bytes before passing to VTIL's lifters) base_address: where the code is mapped in virtual memory (default 0x400000 — the ELF .text convention)

Returns::

{"arch": "x86_64", "base_address": 0x400000,
 "il": {"blocks": [{"vaddr": N, "instructions": [...]}]}}

Each lifted instruction is one of VTIL's IL primitives (mov, add, sub, jmp, if, vmov, etc.). The structure is enough for optimize and emit to work on the output.

On a missing binary, returns {"status": "WARN", "error": "vtil-cli not built", ...} so the agent knows to retry after install.sh.

Inputs: arch (required), code (required), base_address.

optimizeA

Run VTIL optimization passes over a lifted IL tree.

Args: il: the IL tree produced by :func:lift_handler passes: list of pass names to apply in order. The canonical set is dead_store_elimination, branch_folding, mem_dependency; pass names are the C++ enum names in VTIL's optimizer::pass_index.

Returns::

{"il": <optimized il>, "passes_applied": [...]}

The output IL is in the same shape as the input — drop-in replacement for downstream emit calls.

Inputs: il (required), passes.

simplify_lifted_ilA

Run the curated default pass set on a lifted IL tree.

The canonical pass order comes from data/ollvm-pass-catalog.json::_meta.default_pass_order and is curated for the encrypted-VM bytecode handler-lift case (MBA-fold + opaque-predicate-eval + control-flow-unflatten on top of the d810-ng default set).

Args: il: the IL tree produced by :func:lift_handler passes: optional override; when None, the curated default order is used. default_preset: "d810-ng" (the curated set), or "none" to disable simplification entirely.

Returns::

{"il": <optimized il>, "passes_applied": [...],
 "preset": "d810-ng"}

Inputs: il (required), passes, default_preset.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct operation: checking the CLI, lifting code, optimizing IL generically, optimizing with a curated preset, and emitting pseudocode. There is no functional overlap.

    Naming Consistency4/5

    Names follow a verb_noun pattern with underscores, mostly consistent (check_vtil, emit_pseudo_c, lift_handler, optimize, simplify_lifted_il). The verb 'simplify' is slightly different from 'optimize', but both are clear and the pattern is predictable.

    Tool Count5/5

    Five tools is well-scoped for a binary lifting MCP server: verification, lifting, two optimization variants, and output. Neither too few nor too many.

    Completeness4/5

    The core workflow (lift -> optimize -> emit) is fully covered. The only minor gap is the lack of a tool for raw IL inspection or comparison, but the provided set is sufficient for typical reverse engineering tasks.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      F
      maintenance
      Enables AI-assisted reverse engineering by bridging Binary Ninja with Large Language Models through 40+ analysis tools. Provides comprehensive binary analysis capabilities including decompilation, symbol management, type analysis, and documentation generation through natural language interactions.
      50
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLMs to autonomously reverse engineer binaries using Ghidra's capabilities including decompilation, function analysis, automatic renaming, and BSim integration for function similarity matching.
      1
      AGPL 3.0
    • A
      license
      A
      quality
      C
      maintenance
      A multi-backend MCP server that exposes binary analysis capabilities from IDA Pro and Ghidra, allowing LLMs to directly drive reverse-engineering tools via natural language.
      11
      180
      Apache 2.0