protobuf-decompiler

Reconstructs .proto files from Google Protocol Buffers reflection metadata compiled into binaries. Designed for World of Warcraft client analysis.

Supported WoW Versions:

• WoW Retail: 6.0.2 (Warlords of Draenor) through retail build 12.1.0.69933
• WoW Classic: 1.13.2 through MoP Classic build 5.5.3.66290

See Protobuf Version Support Boundary. Clients from build 70032 onward are not supported.

Protobuf Version Support Boundary

Blizzard upgraded the protobuf runtime compiled into WoW clients for the first time in over a decade. Binaries embed a blizzard_protobuf.version string:

Client builds	Protobuf runtime	Supported by this tool
Up to build 69933 (e.g. retail 12.1.0.69933, MoP Classic 5.5.3.66290)	Blizzard fork of protobuf 2.6.1 (protobuf_blz-2.6.1.13)	Yes (final supported range)
Build 70032 and later (e.g. MoP Classic 5.5.4.70032, Classic Era 1.15.9.70003, beta 1.60.1.70245)	Blizzard fork of protobuf 6.30.1 (protobuf_blz-6.30.1, editions support)	No

This release is the last one that supports the protobuf 2.6.1 fork. Future releases will target newer protobuf versions. The 2.6.1-based descriptor handling silently discards edition-era fields (FeatureSet, edition), so binaries from build 70032 onward cannot be reconstructed faithfully.

Features

• Extracts protobuf descriptors from binary files
• Reconstructs .proto files with original structure and dependencies
• Supports Linux and macOS platforms
• Command-line interface with multiple input methods

Quick Start

Prerequisites

Required:

• CMake (≥ 3.28)
• C++17 compatible compiler (GCC or Clang)
• Boost (≥ 1.51) - components: filesystem, system, program_options

Building

Using CMake Presets (Recommended)

# Clone the repository
git clone https://github.com/wowemulation-dev/protobuf-decompiler.git
cd protobuf-decompiler

# List available presets
cmake --list-presets

# Configure and build with a preset (e.g., release build with GCC)
cmake --preset gcc-release
cmake --build --preset gcc-release

# Or for debug builds
cmake --preset gcc-debug
cmake --build --preset gcc-debug

# The binary will be in build/<preset-name>/bin/protobuf_decompiler

Traditional CMake Build

# Clone the repository
git clone https://github.com/wowemulation-dev/protobuf-decompiler.git
cd protobuf-decompiler

# Create build directory and configure
mkdir build && cd build
cmake ..

# Build (automatically handles protobuf 2.6.1 dependency)
make -j$(nproc)

# Optional: Install system-wide
sudo make install

The build system automatically:

• Detects if your system has protobuf 2.6.1 and uses it
• Downloads and builds protobuf 2.6.1 from source if needed
• Handles all dependencies and linking

Usage

# Extract protobuf schemas from binary file
./protobuf_decompiler --binary /path/to/binary

# Scan directory for .protoc files
./protobuf_decompiler --directory /path/to/directory

# Specify output directory
./protobuf_decompiler --binary /path/to/binary --output ./output/<version-build-os-arch>

# Show help and options
./protobuf_decompiler --help

Examples:

# Extract from WoW Classic binary (output organized by version)
./protobuf_decompiler --binary /path/to/classic/client/archive/<version-build-os-arch>/Wow.exe --output ./output/<version-build-os-arch>

# Example with actual version
./protobuf_decompiler --binary ~/Downloads/battle.net/wow_classic/1.13.2.31650.windows-win64/_classic_/Wow.exe --output ./output/1.13.2.31650.windows-win64

# Legacy positional argument (backward compatibility)
./protobuf_decompiler /path/to/binary

# Scan directory for .protoc files
./protobuf_decompiler --directory ./extracted_files/

How It Works

1. Searches executable files for embedded protobuf descriptors
2. Parses protobuf reflection metadata using internal APIs
3. Resolves dependencies between message types and imports
4. Generates .proto files maintaining original structure

Implementation details:

• Direct binary analysis for descriptor extraction
• Two-pass dependency resolution
• Uses protobuf internal API manipulation
• Preserves directory structure in output

Build Options

# Debug build with symbols
cmake -DCMAKE_BUILD_TYPE=Debug .. && make -j$(nproc)

# Use specific compiler
CXX=clang++ cmake .. && make -j$(nproc)

# Use Ninja for faster builds
cmake -G Ninja .. && ninja

# Format code (requires .clang-format in project root)
make format

System Requirements

• Operating System: Linux, macOS
• Architecture: x86_64, ARM64
• Memory: 512MB RAM minimum
• Disk Space: 100MB for build artifacts

Contributing

Submit issues, feature requests, or pull requests.

License

This project is licensed under the MIT License.

Important Notes

• Requires protobuf version 2.6.1 for API compatibility; supports only WoW client builds up to 69933 (see Protobuf Version Support Boundary)
• Tested with World of Warcraft clients (6.0.2+ retail, 1.13.2+ Classic, excluding builds 70032 and later)
• Contains intentional memory leaks to avoid protobuf double-free issues
• Uses pointer arithmetic to access protobuf internal structures
• Windows builds currently not supported in CI due to protobuf 2.6.1 compatibility requirements