unblob: A Recursive Extraction Engine for Firmware and Binary Blobs

The Problem: Unknown Binary Blobs Are a Mess

Firmware images are rarely a single file. They are nested containers: a compressed archive inside a file-system image inside another archive. Reverse engineers and security analysts spend hours manually identifying each layer, extracting it, and then repeating the process on the result. The problem is compounded because many formats have ambiguous magic bytes or are corrupted, so naive tools either miss chunks or produce false positives. unblob addresses this by parsing a blob, identifying each chunk with precise start and end offsets, extracting it, and then recursively processing the extracted content. It also carves out unknown chunks, so nothing is silently dropped. The intended audience is firmware analysts, vulnerability researchers, and anyone who needs to unpack a binary blob quickly and completely.

How unblob Works: Detection, Extraction, and Carving

The core mechanism is a pipeline of format handlers. Each handler knows how to detect a specific format and how to extract it. unblob scans the input blob, and for each chunk it detects, it records the start and end offsets according to the format standard. This precision reduces false positives, which is a common failure in tools that rely on magic-byte matching alone. After extraction, the tool recursively processes the extracted files, up to a configurable depth (default 10). For chunks that do not match any known format, unblob carves them out and reports them as unknown. It also calculates Shannon entropy and chi-square probability for these unknown chunks, which helps spot encrypted or compressed data. The documentation states that this entropy analysis is performed at a configurable depth, with a default of 1 and the option to disable it. The entire process runs without elevated privileges, and it uses multiple processes by default to speed up extraction.

Getting It Running: Installation and External Dependencies

The recommended installation is via pip: 'pip install unblob'. But that is only the Python package. The actual extraction relies on external command-line tools for many formats. On Ubuntu/Debian, the README lists a long apt command that installs e2fsprogs, p7zip-full, unar, zlib1g-dev, liblzo2-dev, lzop, lziprecover, libhyperscan-dev, zstd, lz4, and android-sdk-libsparse-utils. SquashFS support requires a separate sasquatch package, installed via a .deb file. This is a significant setup burden. The Docker image bundles all extractors, which is the easiest path: a single 'docker run' command mounts input and output directories. There is also a system package for Kali Linux and a Nix package. After any installation, you should run 'unblob --show-external-dependencies' to verify that all required tools are present. The README warns that mounted directories must be owned by the same uid:gid when using Docker, which is a practical gotcha.

Command Line and Python API: Two Ways to Drive Extraction

The CLI is straightforward. Running 'unblob firmware.bin' extracts to a directory named '<filename>_extract/' by default. A custom output directory is set with '-e /tmp/output'. The '--report report.json' flag writes a JSON metadata report. Recursion depth is controlled with '-d', and entropy analysis depth with '-n'. The '-S' option skips files whose magic string matches a given prefix, which is useful for ignoring tar headers. The '-P' option loads custom plugins from a path. For automation, the Python API mirrors the CLI. The README shows a minimal example: create an 'ExtractionConfig' with an 'extract_root' and 'randomness_depth', then call 'process_file'. The config accepts the same options as the CLI, including 'max_depth', 'process_num', and 'skip_magic'. This makes unblob embeddable in larger analysis pipelines. The API is documented at unblob.org/api.

Limitations and Failure Modes

The most obvious limitation is the dependency on external extractor tools. If you install only the pip package, many formats will fail silently or produce partial extraction. The '--show-external-dependencies' command helps, but it is up to you to install the right tools for the formats you care about. The recursion depth default of 10 might be too low for deeply nested firmware, but you can raise it with '-d'. The entropy analysis is only calculated for unknown chunks, and it is off by default at depth 0 if you set '-n 0'. More fundamentally, unblob is not a magic-bytes oracle. It relies on format handlers, and if a format is not in the list of 78+, it will be carved as unknown, not extracted. The README mentions that the tool is fuzz-tested, but that does not guarantee every corrupted image will extract cleanly. For highly obfuscated or custom formats, you will need to write your own handler, which requires reading the development guide.

Alternatives: binwalk and Manual Toolchains

The most common alternative is binwalk, which also scans for signatures and extracts embedded files. The key difference is that binwalk historically relies on signature scanning and often requires a separate tool like 'binwalk -e' to run extractors, and it does not always provide precise end offsets. unblob's approach is to use format-specific handlers that know the exact structure, which should reduce false positives and improve extraction accuracy. Another alternative is to manually chain tools like 'dd', 'tar', and 'unsquashfs', but that is slow and error-prone. There is also the 'firmware-mod-kit', which is older and less maintained. The practical difference is that unblob is actively maintained (recent releases in 2026) and provides a Python API, making it easier to integrate into automated pipelines. If you only need to extract a single known format, a dedicated tool like 'unsquashfs' might be simpler, but for mixed blobs, unblob's recursive approach saves time.

Maintenance, License, and Upgrade Considerations

unblob is licensed under the MIT License, which is permissive and allows commercial use without copyleft obligations. The project is not archived, and the last push was in June 2026, with a release on the same day. The versioning scheme (26.6.4) suggests a date-based release cadence, so upgrades are frequent. The README states that dependencies are audited and pinned, which is good for reproducibility but means you should regularly update to get security fixes. The integration test fixtures are stored in Git LFS, so if you want to run the test suite, you need to install Git LFS first. The development setup uses 'uv sync' and requires a Rust toolchain for compiled extensions, which adds complexity if you need to modify the source. For most users, the pip or Docker install is sufficient. The external extractor tools are system packages, so you must track those separately. The '--show-external-dependencies' command is your friend for checking that.

Editorial conclusion

Adopt unblob if you analyze firmware images or other binary blobs and need recursive extraction across dozens of archive, compression, and file-system formats, with unknown chunk carving and entropy metadata. Avoid it if you require a single static binary, if you cannot install external extractor tools, or if your target formats are not in the supported list. Before adopting, verify that all external dependencies are installed by running 'unblob --show-external-dependencies', confirm the default recursion depth of 10 matches your needs, and test on a representative firmware sample to check extraction accuracy for your specific formats.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes