🥯 Bun Extractor

bun-extractor is a lightweight Python tool designed to unpack and extract the contents of standalone executables created using Bun's compile feature (bun build --compile).

It allows you to reverse-engineer bundled binaries to recover the original source code, assets, and directory structure.

🚀 Features

• Zero Dependencies: Written in pure Python 3 using standard libraries.
• Full Extraction: Recovers source code (.js, .ts), assets, and node_modules.
• Metadata Inspection: Displays the entry point ID, compilation flags, and bundle size.
• Cross-Platform: Works on executables compiled for Windows, macOS, and Linux (PE, Mach-O, and ELF) because the Bun payload format is platform-agnostic.

📦 Installation

No installation is required. Just clone the repo or download the script.

git clone https://github.com/yourusername/bun-extractor.git
cd bun-extractor

🛠 Usage

Run the script against any Bun-compiled executable:

python bun_extractor.py ./path/to/my-app

Example Output

[*] Analyzing ./my-app...
[*] Found trailer at offset: 94205125

--- Metadata ---
Blob Size:       102450 bytes
Entry Point ID:  0
Flags:           0b0
Blob Start:      94102675
Module Count:    12

[*] Extracting files to: /users/dev/bun-extractor/my-app_extracted

  [0] index.ts -> 450 bytes
  [1] utils/logger.ts -> 120 bytes
  [2] node_modules/zod/index.js -> 4500 bytes
  ...

[*] Success! Extracted 12 files.

🧠 How it Works

Bun compiles executables by appending a custom data blob to the end of the bun binary. This tool parses that blob based on the internal logic found in StandaloneModuleGraph.zig.

The file structure looks like this (read from the end of the file backwards):

1. Trailer: A magic signature \n---- Bun! ----\n at the very end of the file.
2. Offsets: A 32-byte struct immediately preceding the trailer containing pointers to the data blob and the entry point ID.
3. Data Blob: A memory block containing:
   • A list of CompiledModuleGraphFile structs.
   • Raw file contents.
   • File names.
   • Source maps (if enabled).

The tool reads the offsets, calculates the start of the blob, walks through the module array, and deserializes the file structure onto your disk.

⚠️ Disclaimer

This tool is intended for educational purposes, debugging, and security research. Do not use this tool to reverse engineer or distribute software that you do not have permission to access.

📄 License

Apache License 2.0 © 2026 Alessandro Bellia