Skip to main content
Glama

Universal Asset Ripper


πŸ“– Overview

Universal Asset Ripper is an engine-agnostic extraction and binary reverse engineering platform designed for game developers, modders, and security researchers. It seamlessly bridges native binary format parsers with AI pair-programming agents via the Model Context Protocol (MCP) and integrates into an advanced software reverse engineering (SRE) toolchain.

Whether analyzing Godot archives, Unreal Engine IoStore/PAK containers, Unity IL2CPP metadata, or desktop Windows PE executables, Universal Asset Ripper provides lightning-fast heuristic detection, categorized asset inventories, targeted extraction, and deep binary entropy inspection for cryptographic keys.


Related MCP server: REA (Reverse Engineer Anything)

🎯 Features

  • πŸ” Automatic Engine & Framework Detection (ripper detect) :

    • Heuristics and signature analysis for Unity, Unreal Engine, Godot and Electron (engine electron when an app.asar / resources.pak sits next to an Electron executable).

    • Application framework detection (Delphi, .NET, Electron, Qt, Native C/C++); the PE framework info is kept in details.framework.

    • PE header architecture analysis (x86, x64, ARM64) and encryption flagging.

  • πŸ“¦ 100% Native Pure TypeScript Parsers :

    • Godot PCK : Zero-dependency parser for standalone .pck packages and embedded executables (GDPC magic) supporting format versions 1 through 4.

    • Unreal .pak index (v1-v11) : lists and extracts stored, Zlib and Gzip entries natively, with AES-256 (ECB) decryption of the index and of entries (--aes-key, hex with/without 0x or base64). Oodle and other codecs, and anything the native reader cannot parse, fall back to the repak CLI.

    • Electron : app.asar (incl. .unpacked files) and Chromium resources.pak (v3/v4/v5, extracted as res_<id>.<ext>, extension guessed from magic numbers - heuristic).

    • Godot encrypted PCK : directory and per-file AES-256-CFB decryption with the script encryption key (--aes-key, 64 hex chars); --convert writes .ctex/.stex that wrap a plain PNG/WebP as images.

    • Windows PE (.rsrc) : Complete multi-resolution .ico icon reconstruction, Delphi .dfm form extraction, Win32 dialog template decoding (RT_DIALOG β†’ JSON with title + every control label β€” DLGTEMPLATE and DLGTEMPLATEEX incl. the 01 00 ff ff compiled header order), XML manifests, bitmaps, and raw RCDATA.

  • πŸ“Š Asset Manifest & Inspection (ripper inspect) :

    • Full cataloging across unified categories: textures, 3D meshes, audio, scenes, scripts, shaders, fonts, videos, and manifests.

  • 🎁 Unreal IoStore containers (.utoc/.ucas, UE 4.26+ / UE 5) : Native TOC reader (versions 1-8: chunk table with 40-bit offsets, compression blocks, method names, signatures, directory index) with file listing and chunk extraction (stored/Zlib/Gzip). Oodle and custom codecs are reported as unsupported (no game-side decoder). The same .utoc support flows through the generic ripper inspect / ripper extract CLI commands and MCP tools.

  • πŸ–ΌοΈ Unreal texture decoding (--convert) : After extraction, cooked UE 4.26-4.27 packages (.uasset + .uexp + .ubulk/.uptnl) are parsed for Texture2D exports and their mips are decoded to PNG: uncompressed layouts (BGRA/RGBA/R8/A8/RGB565/4444), DXT1/BC1, DXT5/BC3, BC4, BC5 (normal-map Z rebuilt), BC6H (HDR half-float, tone-mapped to sRGB) and BC7 β€” all 8 BPTC modes, verified against the Khronos specification's worked examples. Unreal 5 packages and unversioned-properties packages are refused with a clear error.

  • βœ… Authenticode signature report (ripper audit) : Every audited binary gets its certificate table read (security directory, WIN_CERTIFICATE entries), its embedded PKCS#7 parsed (signer, certificates, digest and signature algorithms, timestamp / nested-signature attributes listed), the Authenticode file hash recomputed per spec (checksum and security directory entry excluded) and compared to the signed digest, and the signature verified natively (RSA / ECDSA via node:crypto) against the embedded signer certificate. Embedded chain links are checked without any trust store β€” real-world binaries embed signer + intermediate CA but never the root, so an incomplete embedded chain is the norm, reported as such.

  • ⚑ Targeted & Secure Extraction (ripper extract) :

    • Zip Slip / Path Traversal Protection : Strict path resolution validation across all archive extractors (Unreal .pak, IoStore .utoc/.ucas, Godot .pck, Electron .asar, Chromium .pak, and PE resources). Destination paths are verified to reside strictly inside the target output directory (isRelativeTo / assertSafeOutputPath), rejecting any traversal attempt with SecurityError("Tentative de Path Traversal dΓ©tectΓ©e dans l'archive").

    • Category filtering (--categories texture,audio,mesh) and regex/glob filename filtering (--filter).

    • AES-256 keys (--aes-key <key>) for Unreal .pak and Godot PCK; --convert for Godot textures and Unreal textures; Unity export through AssetRipper headless web mode (ASSETRIPPER_PATH).

  • πŸ€– AI-Assisted Binary Analysis (ripper rea-inspect) :

    • Complete vendored morluto/rea engine (v6.8.0) under rea/ with native bridges (Ghidra, Jadx, Hopper, Cutter, Swift LLDB/UI) and direct execution (npm run rea).

    • Automated upstream sync tool (npm run sync:rea:check and npm run sync:rea) to track future releases of morluto/rea and keep vendored source and agent skills updated automatically.

    • Official agent skills in .zcode/skills/: reverse-engineer-anything (35 KB master skill with 7 domain guides for native SRE, Android, runtime observation, environments), leanrea, and clean-room-port.

    • The whole file is scanned in overlapping chunks; false positives are filtered (hex runs longer than 64, counting tables, low entropy, repeated blocks) and counts are reported honestly (N candidates, showing M).

    • --pak <file> verifies every candidate against an Unreal pak (verified keys first); --bundle <file> saves the evidence bundle; --json prints scan + bundle.

    • Sliding-window Shannon entropy scanning to spot 256-bit encryption keys.

    • Proximity search around Rijndael S-Box lookup tables (0x63, 0x7c, 0x77, 0x7b...).

    • Header sniffing and version validation for Unity IL2CPP global-metadata.dat.

    • Automated generation of structured Evidence Bundles formatted for AI agents.

  • πŸ”Œ Integrated Model Context Protocol (MCP) Server (ripper mcp) :

    • Exposes extraction, inspection, and scanning tools over standard I/O for Claude Code, Gemini CLI, Cursor, and Antigravity.

  • 🎨 Downstream Modding Pipeline Ready :

    • Feeds extracted assets and decrypted structures directly into generative game modding frameworks such as rehan-remade/universal-modder (fal.ai / ComfyUI asset replacement and in-game testing).


🧬 Clean-Room Reimplementation Workflow

The PE recon capabilities power a proven inventory β†’ port pipeline for installed Windows software (observation only β€” resources, built-in usage, embedded help; never decompilation):

  1. ripper detect / ripper extract over the installation β†’ dialog, string and help inventories (the feature map)

  2. capture the CLI tools' built-in usage text (authoritative)

  3. write a precise inventory document (executables, DLL→OSS mapping, windows, options, coverage statuses)

  4. clean-room port (e.g. Rust) verified against an in-process mock server

Packaged as the clean-room-port skill (.zcode/skills/ in this repository), documented in docs/workflow-clean-room-reimplementation.md. Worked examples:

  • the Bitvise SSH Client port β€” CLI + egui GUI + Bitvise option compatibility β€” in bitvise-rs/, with its precise inventory.

  • the Notepad++ port β€” npp-core + npp-cli + npp-gui (multi-tab editor, line endings, encodings, search) in modern Rust 1.99.1 (d:\git\notepadpp-rs), with its inventory.

πŸ—οΈ Architecture

                                β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                                β”‚   Universal Asset Ripper       β”‚
                                β”‚   (CLI & MCP stdio Server)     β”‚
                                β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
                                               β”‚
                    β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”΄β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
                    β–Ό                                                     β–Ό
      [ EngineDetector Engine ]                                 [ ReaBridge & AI Hub ]
  (Unity, Unreal, Godot, Electron, PE)                        (BinaryScanner, Shannon Entropy,
                    β”‚                                         AES-256 discovery, Evidence)
       β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”¬β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”                           β”‚
       β–Ό            β–Ό            β–Ό            β–Ό              β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”Όβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
  [ Godot ]    [ Unreal ]    [ Unity ]   [ PE Soft. ]        β–Ό            β–Ό            β–Ό
  Adapter       Adapter       Adapter     Adapter       [ Ghidra ]   [ Cpp2IL ]    [ Frida ]
  (Native       (repak /    (AssetRipper (Resource      (Native SRE   (IL2CPP ->   (Runtime
  PCK reader)  CUE4Parse)    CLI bridge)  Extractor)    Decompiler)    C# .NET)     Hooking)

πŸš€ Installation & Quick Start

Prerequisites

  • Node.js >= 22.0.0

  • npm >= 10.0.0

Global CLI Installation

Clone and build the repository locally:

git clone https://github.com/laurentvv/universal-asset-ripper.git
cd universal-asset-ripper
npm install
npm run build
npm link

Verify your installation:

ripper --help

πŸ’» CLI Usage

1. Detect Game Engine & Framework

Inspect any folder, game directory, or executable:

ripper detect "C:/Games/MyGame"
# Or point directly to an executable:
ripper detect "C:/Games/MyGame/MyGame.exe"

2. Inspect Package Manifest

Display categorized file counts and size breakdowns without writing to disk:

ripper inspect "C:/Games/MyGame/game.pck"
# Encrypted Unreal pak index / Godot directory: pass the key
ripper inspect "PakChunk0.pak" --aes-key 0x4A6B... --json

3. Extract Assets

Extract all assets or filter by specific categories:

# Full extraction
ripper extract "C:/Games/MyGame" -o "./extracted"

# Extract only textures and audio files
ripper extract "C:/Games/MyGame" -o "./extracted" --categories texture,audio

# Extract Unreal PAK with AES key
ripper extract "C:/Games/MyGame/Content/Paks/PakChunk0.pak" -o "./extracted" --aes-key 0x4A6B...

# Godot: convert PNG/WebP-backed .ctex/.stex textures to images
ripper extract game.pck -o ./extracted --convert

# Electron app (app.asar and resources.pak)
ripper extract "C:/Apps/MyElectronApp" -o ./extracted

# Unity: needs AssetRipper.GUI.Free; set ASSETRIPPER_PATH (file or folder) or add it to PATH
ripper extract "C:/Games/UnityGame" -o ./extracted

4. Deep Binary Inspection (AI Evidence Bundle)

Scan an executable for cryptographic keys, S-Box constants, and IL2CPP metadata:

ripper rea-inspect "C:/Games/MyGame/Game-Win64-Shipping.exe"
# Verify candidates against a pak, save the evidence bundle, machine-readable output
ripper rea-inspect Game-Win64-Shipping.exe --pak Content/Paks/PakChunk0.pak --bundle ./evidence.json
ripper rea-inspect Game-Win64-Shipping.exe --json   # { scan, bundle }

5. Multi-Engine Disassembly & Decompilation

Drive GNU Binutils, NSA Ghidra, Cutter/Rizin, Hopper, and IDA Pro:

# List all 5 decompiler engines and readiness status
ripper decompilers

# Disassemble binary machine code (Intel syntax with opcodes & offsets)
ripper disasm "C:/Program Files/Notepad++/notepad++.exe" -n 50

# Dump symbols, functions, and imported DLL APIs
ripper symbols "C:/Program Files/Notepad++/notepad++.exe" --filter "Create"

# Decompile a function to C pseudocode with Ghidra
ripper decompile "target.exe" -f "MainEntryPoint" --backend ghidra -o ./decompiled.c

# Run setup guide for external engines
npm run setup:decompilers

6. Automated Directory Audit & Mandatory Decompilation Pipeline

Point ripper audit (or alias ripper rea-dir) to any application or game directory to automatically launch the full end-to-end recovery pipeline:

# Run full automated audit with mandatory C decompilation (active by default)
ripper audit "C:/Program Files/Notepad++" -o ./audit-results

# Skip decompilation if only performing visual/surface audit
ripper audit "C:/Program Files/Notepad++" -o ./audit-results --no-decompile

The automated auditor detects the engine, scans all primary and sibling executables/DLLs, decompiles entrypoints and exported plugin functions to C via the native headless NSA Ghidra/Sleigh engine (< 900ms per function, zero Java), extracts Win32 dialogs and visual resources, recovers CLI switches and exported plugin APIs, categorizes all configuration models (syntax, themes, autocomplete, function outlines), and writes actionable clean-room recovery recommendations.

See the detailed Decompiler Guide and Complete Functional REA Workflow.

All commands accept --json (pure JSON on stdout).

Honest limitations

  • The native pak reader was written from the UE / repak format and tested against synthetic paks built by a test writer, not against commercial game archives. Pak v12+, Oodle and Zstd are not handled natively (Oodle goes through repak, which unpacks whole containers, so it cannot honour --categories/--filter).

  • The IoStore reader follows the same discipline: TOC versions 1-8 with a 144-byte header, tested against synthetic containers (encrypted directory indexes, AES-keyed chunk streams and Oodle blocks stay out of reach without the game's own decoder).

  • Unreal texture parsing covers UE 4.26-4.27 cooked packages (file version -7, versioned properties). Unreal 5 packages and packages written without property names are refused β€” reading them needs each game's own type layouts.

  • The Authenticode reader checks what the file alone can prove: digest match, signature validity against the embedded certificate, and embedded chain links. Windows trust, revocation (CRL/OCSP) and catalog-signed binaries (no embedded signature, e.g. Windows 11 notepad.exe) are out of reach by design.

  • Godot encryption (AES-256-CFB, md5|size|iv|data) follows the engine source but is validated only against our own encryptor. .ctex conversion lifts plain PNG/WebP payloads only (no WebP-to-PNG re-encoding, no VRAM-compressed textures).

  • AssetRipper is driven through its headless web API (form field Path); the endpoints are tested with a fake server only, and --categories/--filter are not supported for Unity.

  • Electron: unpacked resources/app folders are not listed; Chromium .pak extension guessing is heuristic.

  • Key verification with a plain (unencrypted) pak index can only probe an encrypted entry; otherwise candidates stay unverifiable.


πŸ€– MCP Server Setup (AI Agents)

Universal Asset Ripper runs as a standard Model Context Protocol (MCP) server over stdio. It connects natively with Claude Code, Gemini CLI, Cursor, and Antigravity.

Add the server to your mcpServers configuration file:

{
  "mcpServers": {
    "universal-asset-ripper": {
      "command": "node",
      "args": ["C:/git/universal-asset-ripper/dist/cli/index.js", "mcp"]
    }
  }
}

Restricting file access

By default the MCP tools accept any path. To confine an agent to specific folders, pass --root (repeatable) or set UAR_ALLOWED_ROOTS (path-delimited: ; on Windows, : elsewhere). Every targetPath, binaryPath, pakPath and outputDir must then resolve (symlinks followed) inside one of the roots, otherwise the call returns an error.

"args": ["C:/git/universal-asset-ripper/dist/cli/index.js", "mcp", "--root", "D:/Games", "--root", "D:/Extracted"]

Tools Exposed to Agents

Tool Name

Description

ripper_detect

Run heuristic analysis to detect the game engine, architecture, and container type.

ripper_inspect

Return a complete manifest of files with counts and sizes grouped by category.

ripper_extract

Extract assets to disk with category filters and optional AES-256 decryption keys.

ripper_scan_binary

Run Shannon entropy scans, find AES keys (optional pakPath verification), and extract IL2CPP metadata headers.


πŸ”¬ Reverse Engineering Ecosystem

Universal Asset Ripper forms the upstream reconnaissance and extraction hub within a comprehensive SRE toolchain:

Tool

Category

Specialty & Role in Pipeline

morluto/rea

Agentic SRE

Autonomous LLM agents consuming Evidence Bundles to plan reverse engineering steps.

Ghidra

Static SRE

Deep native disassembly and C pseudocode decompilation (x86/x64/ARM).

Cpp2IL

Unity IL2CPP

Reconstructs executable CIL (.NET) bytecode from GameAssembly.dll for decompilation in dnSpy/ILSpy.

JADX

Android SRE

Dex-to-Java decompiler for unpacking APK/AAB packages, manifests, and JNI bridges.

Frida

Dynamic SRE

Runtime memory hooking to capture live AES keys and dump uncompressed asset buffers.

universal-modder

Modding Studio

Downstream mod injection, generative AI assets (fal.ai/ComfyUI), and in-game automated testing.


πŸ“š Technical Documentation


πŸ§ͺ Testing

The test suite validates parser accuracy against synthetically generated binary containers (PE headers, Godot PCK archives, and AES memory blocks):

npm test

Check your environment (Node.js, repak, AssetRipper, rea) with ripper doctor (--json for machine-readable output).


πŸ› οΈ Development

npm ci                  # install
npm run lint            # ESLint (flat config, typescript-eslint)
npx tsc --noEmit        # type check
npm run build           # compile to dist/
npm test                # build + vitest
npm run test:coverage   # vitest with v8 coverage
npm run clean           # remove dist/ and coverage/

CI (.github/workflows/ci.yml) runs lint, build and tests on Ubuntu and Windows with Node 22 and 24.


πŸ“„ License

MIT Β© laurentvv

Tool Schema Changelog

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

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      C
      quality
      B
      maintenance
      Enables an AI agent to auto-detect a game's engine (Unity, Unreal, Godot, Java, or native) from its files and then inspect, search, and patch the underlying binaries with in-process PE analysis, hex editing, pattern scanning, string extraction, checksums, diffing, and disassembly. Everything runs locally and offline with no cloud dependency or telemetry.
      100
      54 npm
      5
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to inspect and decompile software they have no source for β€” Android APKs, Electron bundles, .NET assemblies, and Go, Rust or WASM binaries β€” plus adb device interaction, through a token-guarded Streamable HTTP MCP endpoint, stdio MCP, or a CLI. Ghidra-powered native binary decompilation can be opted in at startup for ELF, PE and Mach-O targets.
      6
      Do What The F*ck You Want To Public
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding agents to inspect and reverse-engineer large binaries through bounded stdio JSON-RPC 2.0 tools for graph queries, SSA facts, path solving, runtime grounding, and mod scaffolding.
      1
      AGPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents (and a matching CLI) to inspect native binaries, JavaScript/Electron apps, .NET assemblies, Go/Rust/WASM artifacts, EVM bytecode, SQLite databases, recorded crashes, and websites without source code, explaining how features work and returning the evidence and limitations behind each conclusion. Analysis runs locally, using optional Hopper, Ghidra, or IDA providers for native targets.
      369,596 npm
      MIT