Vulture

A comprehensive toolkit for analyzing, decompiling, and deobfuscating Minecraft mods. Vulture picks apart mod JARs to reveal their inner workings, making it perfect for security researchers, mod developers, and anyone who needs to inspect mod behavior in a safe, isolated environment.

Features

• Static Analysis: Analyze mod JAR files without execution
• Decompilation: Convert compiled bytecode back to readable Java source
• Deobfuscation: Apply MCP/ProGuard mappings to restore readable names
• Recompilation: Compile decompiled Java source back into JAR files
• Security Detection: Automatically identify suspicious patterns (webhooks, token access, network code)
• Isolated Execution: All tools run in Docker containers for safety
• Multiple Decompilers: Support for CFR, JD-CLI, and Fernflower
• Auto-Install Tools: Automatically downloads and manages decompiler versions
• Auto-Download Mappings: Automatically downloads Minecraft version mappings from MCPBot
• Version Detection: Automatically detects Minecraft version from mod JAR files
• Configuration Management: Customizable settings via configuration file

Requirements

• Python 3.8+
• Docker and Docker Compose (recommended)
• Java 8+ (optional, if not using Docker)

Platform Support:

• Windows (PowerShell/CMD)
• macOS (Terminal)
• Linux (Bash)

Quick Start

Automatic Processing (Easiest Method)

Simply place your JAR files in the input/ directory and run the platform-specific script:

macOS:

• Double-click start/Run Vulture (macOS).command

Windows:

• Double-click start/Run Vulture (Windows).bat

Linux:

• Run: bash start/Run\ Vulture\ \(Linux\).sh

The script will:

1. Build the Docker image (if needed)
2. Automatically install required tools (CFR, JD-CLI, SpecialSource) on first run
3. Ask you what to do:
   • Decompile: Process JARs from input/to_be_decompiled/ → saves to output/decompiled/
   • Compile: Process Java source from input/to_be_compiled/ → saves to output/compiled/
   • Both: Decompile then compile in sequence
4. Automatically detect Minecraft version from mod JAR files
5. Automatically download mappings for the detected version (if available)
6. Optionally deobfuscate using downloaded or local mappings

Manual Docker Usage

For advanced users who want to run tools manually:

# Build the Docker image
docker compose -f _internal/docker/docker-compose.yml build

# Run analysis on a mod
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/mod_analyzer.py input/your_mod.jar

# Decompile a mod (auto-detects version and downloads mappings)
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/mod_deobfuscator.py input/your_mod.jar --output output/mod_name

# Decompile with specific version
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/mod_deobfuscator.py input/your_mod.jar --mc-version 1.12.2 --output output/mod_name

# Install/update tools manually
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/tool_manager.py --install-tools

# Download mappings for a specific version
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/tool_manager.py --download-mappings 1.8.9

Note: For most users, the automatic processing scripts are recommended.

Using Local Python Environment

For local development (not recommended for most users):

On Linux/macOS:

# Setup virtual environment
bash scripts/linux/setup.sh  # or scripts/macos/setup.sh
source venv/bin/activate

# Analyze a mod
python src/mod_analyzer.py input/your_mod.jar

# Decompile a mod
python src/mod_deobfuscator.py input/your_mod.jar --output output/mod_name

On Windows:

REM Setup virtual environment
scripts\windows\setup.bat
venv\Scripts\activate.bat

REM Analyze a mod
python src\mod_analyzer.py input\your_mod.jar

REM Decompile a mod
python src\mod_deobfuscator.py input\your_mod.jar --output output\mod_name

Note: Docker is the recommended method. Local setup requires Java 8+ and manual decompiler installation.

Project Structure

.
├── start/                          # Launcher scripts (double-click to run!)
│   ├── Run Vulture (macOS).command
│   ├── Run Vulture (Windows).bat
│   └── Run Vulture (Linux).sh
├── input/                          # Input directories
│   ├── to_be_decompiled/           # Place JAR files here to decompile
│   └── to_be_compiled/             # Place Java source here to compile
├── output/                         # Output directories
│   ├── decompiled/                 # Decompiled Java source code
│   └── compiled/                   # Recompiled JAR files
├── _internal/                      # Backend files (hidden from users)
│   ├── docker/                     # Docker configuration
│   │   ├── Dockerfile
│   │   ├── docker-compose.yml
│   │   └── .dockerignore
│   └── src/                        # Source code
│       ├── mod_analyzer.py
│       ├── mod_deobfuscator.py
│       ├── mod_compiler.py
│       └── process_all.sh
├── requirements.txt                # Python dependencies
├── LICENSE                         # License file
└── README.md                       # This file

Usage

Mod Analyzer

Analyzes mod structure and detects security patterns without modifying the JAR:

# Basic analysis (inside Docker container)
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/mod_analyzer.py input/mod.jar

# Save results to JSON
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/mod_analyzer.py input/mod.jar --json

The analyzer reports:

• Class and resource listings
• Mod metadata (mcmod.info)
• Security patterns (webhooks, token access, network code)
• Suspicious string patterns

Mod Deobfuscator

Decompiles and optionally deobfuscates mods:

# Basic decompilation (inside Docker container, auto-detects version)
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/mod_deobfuscator.py input/mod.jar --output decompiled/mod_name

# With MCP mappings (deobfuscation)
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/mod_deobfuscator.py input/mod.jar mappings/joined.srg --output decompiled/mod_name

# Choose specific decompiler
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/mod_deobfuscator.py input/mod.jar --decompiler jd-cli --output decompiled/mod_name

Supported Decompilers:

• CFR (default): Best accuracy, handles modern Java features
• JD-CLI: Fast, good for quick inspection
• Fernflower: IntelliJ-style output (requires manual download)

Mod Compiler

Compiles decompiled Java source code back into JAR files:

# Compile decompiled source to JAR (inside Docker container)
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/mod_compiler.py decompiled/mod_name compiled/mod_name_recompiled.jar

# With classpath for dependencies
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/mod_compiler.py decompiled/mod_name compiled/mod_name_recompiled.jar -cp libs/*

The compiler:

• Compiles all Java files in the source directory
• Creates a JAR file with proper structure
• Includes resources and manifest
• Outputs ready-to-use JAR files for Minecraft

Obtaining Mappings

Mappings translate obfuscated Minecraft names back to readable ones. Required for proper deobfuscation.

Minecraft uses ProGuard obfuscation, which converts readable names to short ones:

• Minecraft.getMinecraft() → a.a()
• Session.getToken() → b.c()

Mappings reverse this process to restore readable names.

Automatic Download (Recommended)

Vulture can automatically download mappings for detected Minecraft versions:

# Mappings are auto-downloaded when decompiling
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/mod_deobfuscator.py input/mod.jar

# Or download manually for a specific version
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/tool_manager.py --download-mappings 1.8.9

Manual Download

MCPBot (Recommended for older versions)

# Download for Minecraft 1.8.9
wget http://export.mcpbot.bspk.rs/mcp_snapshot/1.8.9/mcp_snapshot-1.8.9.zip
unzip mcp_snapshot-1.8.9.zip -d mappings/

Forge Mappings

Forge provides official mappings for recent versions:

• Visit https://files.minecraftforge.net/
• Download *-mappings.zip for your Minecraft version
• Extract to mappings/ directory

ProGuard Mapping File

If you have a ProGuard mapping.txt file:

docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/mod_deobfuscator.py input/mod.jar mappings/mapping.txt --output output/mod_name

Decompilation Quality

What decompiles well:

• Simple classes and methods
• Standard Java patterns
• Public APIs and interfaces

What may not decompile perfectly:

• Lambda expressions (may show as synthetic methods)
• Obfuscated code (variable names lost)
• Inline optimizations (may be restructured)

Note: Decompiled code may not be 100% accurate, especially with heavy obfuscation. Variable names are often auto-generated.

Docker Details

The Docker image includes:

• Java 8 (Eclipse Temurin)
• Python 3 with required dependencies
• CFR decompiler (auto-downloaded)
• JD-CLI decompiler (auto-downloaded)
• SpecialSource (for applying mappings)

Volume Mounts:

• ./input → /workspace/input (read-only)
• ./output → /workspace/output (read-write)
• ./mappings → /workspace/mappings (read-only)

Interactive Shell:

On Linux/macOS:

docker compose -f _internal/docker/docker-compose.yml run --rm vulture
# You're now inside the container at /workspace

On Windows:

docker compose -f _internal/docker/docker-compose.yml run --rm vulture
REM You're now inside the container at /workspace

Output Structure

When you run the automatic processing, results are saved in the output/ directory:

output/
├── mod-name_analysis.json          # Analysis report (JSON format)
└── mod-name/                       # Decompiled source code
    ├── summary.txt                 # Decompilation summary
    └── [package structure]/        # Organized Java source files
        └── *.java                  # Decompiled class files

Analysis JSON contains:

• Mod metadata and file counts
• Class analysis (GUI, network, data classes)
• Security flags and suspicious patterns
• Resource listings

Decompiled Code includes:

• All Java source files organized by package
• Readable code structure (variable names may be auto-generated)
• Summary of decompilation process

Security Analysis

The tools automatically detect common malicious patterns:

• Discord webhook URLs
• Token/session access patterns
• HTTP/HTTPS network requests
• Reflection usage for obfuscation
• Suspicious string patterns

Example output:

Security Analysis Results:
- Webhook references found in: com.example.ModClass
- Token access detected in: com.example.SessionUtils
- Network code found in: com.example.NetworkHandler

Tool Management

Vulture includes a tool manager that automatically handles decompiler installations and updates:

# Install all tools (CFR, JD-CLI, SpecialSource)
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/tool_manager.py --install-tools

# Install specific tool
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/tool_manager.py --install-cfr
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/tool_manager.py --install-jd-cli
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/tool_manager.py --install-specialsource

# Force reinstall (download latest versions)
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/tool_manager.py --install-tools --force

Tools are automatically installed on first use, but you can pre-install them for faster startup.

Configuration

Vulture supports configuration files for customizing default behavior:

# View current configuration
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/config.py --list

# Set configuration value
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/config.py --set default_mc_version 1.12.2
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/config.py --set auto_download_tools true

# Get configuration value
docker compose -f _internal/docker/docker-compose.yml run --rm vulture python3 /workspace/config.py --get default_decompiler

Configuration is saved to ~/.vulture_config.json (or /workspace/.vulture_config.json in Docker).

Troubleshooting

Decompiler not found

• Tools are automatically installed on first use
• Run python3 /workspace/tool_manager.py --install-tools to manually install
• Or manually download decompiler JARs to tools/ directory

Mappings file not found

• Mappings are automatically downloaded for detected versions
• Run python3 /workspace/tool_manager.py --download-mappings <version> to manually download
• Or download mappings using methods described above and place in mappings/ directory

Version detection fails

• Specify version manually: --mc-version 1.8.9
• Check mod JAR filename and mcmod.info for version hints

Java not found (local environment)

• Install Java 8+ or use Docker instead

Docker build fails

docker compose down
docker compose build --no-cache

Auto-download fails

• Check internet connection
• Use --no-auto-download flag to disable auto-downloads
• Manually download tools/mappings as described above

Limitations

• Decompiled code may not be 100% accurate, especially with heavy obfuscation
• Some control flow may be simplified or altered
• Variable names are often lost and regenerated
• Large mods may take several minutes to decompile

Legal and Ethical Considerations

• Only analyze mods you own or have explicit permission to analyze
• Use findings responsibly and report vulnerabilities through proper channels
• This toolkit is for educational and security research purposes
• Respect intellectual property and licensing of analyzed mods

Resources

• CFR Decompiler
• JD-GUI
• MCPBot
• SpecialSource
• Minecraft Forge

License

This project is provided for educational use only. Use responsibly and ethically.