unblob

Genau, schnell und einfach zu bedienendes Extraktionspaket für binäre Blobs.

unblob analysiert unbekannte binäre Blobs auf 78+ Archiv-, Komprimierungs- und Dateisystemformate, extrahiert deren Inhalt rekursiv und schnibbelt unbekannte Stücke heraus. Es ist der perfekte Begleiter zum Extrahieren, Analysieren und Reverse-Engineering von Firmware-Images.

Demo

Funktionen

• 78+ unterstützte Formate — Archive, Komprimierungsströme und Dateisysteme, einschließlich SquashFS, JFFS2, UBI/UBIFS, ext, CPIO, ZIP, 7-Zip, gzip, XZ, LZMA, LZ4 und viele mehr. Siehe die vollständige Liste.
• Rekursive Extraktion — extrahiert Container innerhalb von Containern bis zu einer konfigurierbaren Tiefe (Standard: 10 Ebenen).
• Präzise Erkennung von Blöcken — identifiziert sowohl Start- als auch Endoffsets jedes Blocks gemäß dem Formatstandard, wodurch Fehlalarme minimiert werden.
• Carving unbekannter Blöcke — schnibbelt Daten heraus und meldet sie, die keinem bekannten Format entsprechen, und identifiziert automatisch Null-/0xFF-Padding.
• Entropieanalyse — berechnet Shannon-Entropie und Chi-Quadrat-Wahrscheinlichkeit für unbekannte Blöcke, nützlich zum Erkennen verschlüsselter oder komprimierter Daten.
• JSON-Metadatenberichte — erzeugt strukturierte Berichte mit Block-Offsets, Größen, Entropie, Dateieigentümer, Berechtigungen, Zeitstempeln und mehr.
• Mehrfachverarbeitung — verwendet standardmäßig alle verfügbaren CPU-Kerne für schnelle Extraktion.
• Erweiterbares Plugin-System — schreiben Sie benutzerdefinierte Format-Handler und Extraktoren und laden Sie sie zur Laufzeit mit --plugins-path.
• Keine erhöhten Rechte erforderlich — läuft sicher als normaler Benutzer.
• Kampferprobt — Fuzz-getestet gegen ein großes Korpus von Firmware-Images; basiert auf geprüften, fixierten Abhängigkeiten.

Installation

pip (empfohlen für die meisten Benutzer)

pip install unblob

Installieren Sie dann die erforderlichen externen Extraktionswerkzeuge. Auf Ubuntu/Debian:

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

Für SquashFS-Unterstützung installieren Sie auch sasquatch:

curl -L -o sasquatch_1.0.deb "https://github.com/onekey-sec/sasquatch/releases/download/sasquatch-v4.5.1-6/sasquatch_1.0_$(dpkg --print-architecture).deb"
sudo dpkg -i sasquatch_1.0.deb && rm sasquatch_1.0.deb

Überprüfen Sie, ob alle Extraktionswerkzeuge verfügbar sind:

unblob --show-external-dependencies

Docker (alles enthalten)

Das Docker-Image bündelt alle Extraktionswerkzeuge – keine zusätzliche Einrichtung erforderlich:

docker run \
  --rm \
  --pull always \
  -v /path/to/extract-dir:/data/output \
  -v /path/to/files:/data/input \
  ghcr.io/onekey-sec/unblob:latest /data/input/firmware.bin

Hinweis: Bereitstellungspfade müssen demselben uid:gid gehören. Auf Mehrbenutzersystemen fügen Sie -u $UID:$GID zum Befehl hinzu.

Kali Linux

sudo apt install unblob

Nix

nix profile install nixpkgs#unblob

Oder fügen Sie es Ihrer NixOS-/home-manager-Konfiguration hinzu – siehe die Installationsdokumentation für Flake- und Overlay-Beispiele.

Aus dem Quellcode

git clone https://github.com/onekey-sec/unblob.git
cd unblob
uv sync --no-dev
uv run unblob --show-external-dependencies

Erfordert Python ≥ 3.10, uv und eine Rust-Toolchain (für die kompilierten Erweiterungen).

Verwendung

Befehlszeile

Eine Datei extrahieren (Ausgabe geht standardmäßig an <Dateiname>_extract/):

unblob firmware.bin

Ein benutzerdefiniertes Ausgabeverzeichnis angeben:

unblob -e /tmp/output firmware.bin

Einen JSON-Metadatenbericht erstellen:

unblob --report report.json firmware.bin

Rekursionstiefe begrenzen und Entropieanalyse aktivieren:

unblob -d 5 -n 2 firmware.bin

Dateien überspringen, die einem magischen Zeichenfolge-Präfix entsprechen:

unblob --skip-magic "POSIX tar archive" firmware.bin

Ein benutzerdefiniertes Handler-Plugin laden:

unblob -P ./myplugins/ firmware.bin

Vollständige CLI-Referenz

Usage: unblob [OPTIONS] FILE

Options:
  -e, --extract-dir DIRECTORY     Extract the files to this directory.
  -f, --force                     Force extraction even if outputs already exist.
  -d, --depth INTEGER             Recursion depth (default: 10).
  -n, --entropy-depth INTEGER     Entropy calculation depth (default: 1; 0 = off).
  -P, --plugins-path PATH         Load plugins from the provided path.
  -S, --skip-magic TEXT           Skip files with a given magic prefix.
  -p, --process-num INTEGER       Number of parallel worker processes (default: CPU count).
  --report PATH                   Write a JSON metadata report to this file.
  -k, --keep-extracted-chunks     Keep extracted chunks on disk.
  --delete-extracted-files TEXT   Delete intermediate files after extraction.
  -v, --verbose                   Increase verbosity (-v, -vv, -vvv).
  --show-external-dependencies    List required external tools and their status.
  -h, --help                      Show this message and exit.

Python-API

from pathlib import Path
from unblob.processing import ExtractionConfig, process_file

config = ExtractionConfig(
    extract_root=Path("/tmp/output"),
    randomness_depth=1,
)

result = process_file(config, Path("firmware.bin"))

Um auch einen JSON-Bericht zu schreiben:

process_file(config, Path("firmware.bin"), report_file=Path("report.json"))

ExtractionConfig akzeptiert dieselben Optionen wie die CLI: max_depth, process_num, skip_magic, force_extract, keep_extracted_chunks und mehr. Siehe die API-Referenz für die vollständige Liste.

Testen

unblob verwendet pytest. Integrations-Testvorrichtungen werden in Git LFS gespeichert.

# Install Git LFS (one-time setup)
git lfs install

# Install all development dependencies
uv sync --all-extras --dev

# Run the full test suite
uv run pytest tests/ -v

Dokumentation

Die vollständige Dokumentation ist verfügbar unter https://unblob.org:

• Installation
• Benutzerhandbuch
• Unterstützte Formate
• API-Referenz
• Entwicklungsleitfaden — Schreiben benutzerdefinierter Handler, Extraktoren und Plugins
• Mitwirkungsleitfaden

Mitwirken

Beiträge sind willkommen! Wenn Sie Unterstützung für ein neues Format hinzufügen oder ein bestehendes verbessern möchten:

1. Öffnen Sie ein Issue, um das Format zu beschreiben (Hexdumps, Spezifikationslinks und Beispieldateien helfen sehr).
2. Lesen Sie den Entwicklungsleitfaden, um zu lernen, wie man Handler und Extraktoren schreibt.
3. Forken Sie das Repository, implementieren Sie Ihre Änderungen und öffnen Sie einen Pull-Request.

Wenn Sie einfach nur ein Format unterstützt haben möchten und es nicht selbst implementieren wollen, öffnen Sie ein Issue – wir werden in Betracht ziehen, es hinzuzufügen.

Siehe CONTRIBUTING für weitere Details.

Lizenz

unblob ist unter der MIT-Lizenz lizenziert.