Repolode
Submit
onekey-sec

onekey-sec/unblob

Command-line tool that recursively extracts files from 78+ archive, compression and file-system formats and carves out unknown chunks in binary blobs.

View on GitHubWebsite
Stars
2,634
Forks
159
Open issues
56
Last commit
2 days ago

What is it?

unblob takes an unknown binary blob, such as a firmware image, and finds the container formats hidden inside it. It parses known archive, compression and file-system formats including SquashFS, JFFS2, UBI/UBIFS, ext, CPIO, ZIP, 7-Zip, gzip, XZ and LZMA, then extracts their contents recursively up to a configurable depth.

Data that does not match any known format is carved out as unknown chunks, with null and 0xFF padding identified automatically. Entropy and chi-square analysis of these chunks helps spot encrypted or compressed regions. A JSON report records chunk offsets, sizes, entropy, ownership, permissions and timestamps.

The tool runs as a regular user and uses multiple CPU cores by default. Custom format handlers can be loaded at runtime through a plugin path. It is installable via pip, Docker, Nix and Kali Linux packages, and it depends on several external extractor utilities.

Key features

  • 01Supports 78+ archive, compression and file-system formats such as SquashFS, JFFS2, UBIFS and ZIP.
  • 02Extracts nested containers recursively up to a configurable depth.
  • 03Detects start and end offsets of each chunk according to the format standard.
  • 04Carves unknown data and identifies null or 0xFF padding automatically.
  • 05Computes Shannon entropy and chi-square values for unknown chunks.
  • 06Writes JSON reports with offsets, sizes, ownership and permissions.
  • 07Accepts custom format handlers through a runtime plugin path.

Use cases

  • Unpacking firmware images to inspect their file systems during reverse engineering.
  • Locating encrypted or compressed regions in a binary blob using entropy results.
  • Batch extracting embedded archives from device dumps in a CI or analysis pipeline.
  • Adding support for a proprietary container format through a custom handler.

Quick start

  1. 1

    Install unblob from PyPI with pip

    pip install unblob
  2. 2

    Install the required external extractor tools on Ubuntu/Debian

    sudo apt install android-sdk-libsparse-utils e2fsprogs p7zip-full unar zlib1g-dev liblzo2-dev lzop lziprecover libhyperscan-dev zstd lz4
  3. 3

    Verify that all extractors are available

    unblob --show-external-dependencies
  4. 4

    Extract a firmware file

    unblob firmware.bin

Things to know

  • Requires installing several external extractor tools separately unless you use Docker.
  • SquashFS support needs an additional separately installed tool, sasquatch.

In collections

Reverse engineering toolsEmbedded systems & microcontroller projects

Topics

#firmware#reverse-engineering#extraction#binary-analysis#archive#file-system#forensics#compression#filesystem#python

FAQ

What is unblob?
Command-line tool that recursively extracts files from 78+ archive, compression and file-system formats and carves out unknown chunks in binary blobs. unblob takes an unknown binary blob, such as a firmware image, and finds the container formats hidden inside it. It parses known archive, compression and file-system formats including SquashFS, JFFS2, UBI/UBIFS, ext, CPIO, ZIP, 7-Zip, gzip, XZ and LZMA, then extracts their contents recursively up to a configurable depth.
Is unblob free to use? What license does it have?
unblob is open source under the MIT license. Check the license terms before using it in commercial products.
Is unblob still maintained?
Actively maintained. The last commit to unblob was on Nov 5, 2026.
What can I use unblob for?
Unpacking firmware images to inspect their file systems during reverse engineering. Locating encrypted or compressed regions in a binary blob using entropy results. Batch extracting embedded archives from device dumps in a CI or analysis pipeline. Adding support for a proprietary container format through a custom handler.
How do I install unblob?
Install unblob from PyPI with pip: pip install unblob Install the required external extractor tools on Ubuntu/Debian: sudo apt install android-sdk-libsparse-utils e2fsprogs p7zip-full unar zlib1g-dev liblzo2-dev lzop lziprecover libhyperscan-dev zstd lz4 Verify that all extractors are available: unblob --show-external-dependencies Extract a firmware file: unblob firmware.bin
Where can I get unblob?
The source code and installation instructions are on GitHub: https://github.com/onekey-sec/unblob

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects