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: