unblob

Suite d'extraction précise, rapide et facile à utiliser pour les blobs binaires.

unblob analyse les blobs binaires inconnus pour 78+ formats d'archives, de compression et de systèmes de fichiers, extrait leur contenu de manière récursive et extrait les parties inconnues. C'est le compagnon idéal pour l'extraction, l'analyse et la rétro-ingénierie d'images de firmware.

---

Démo

---

Fonctionnalités

• 78+ formats pris en charge — archives, flux de compression et systèmes de fichiers incluant SquashFS, JFFS2, UBI/UBIFS, ext, CPIO, ZIP, 7-Zip, gzip, XZ, LZMA, LZ4, et bien d'autres. Voir la liste complète.
• Extraction récursive — extrait des conteneurs dans des conteneurs jusqu'à une profondeur configurable (par défaut : 10 niveaux).
• Détection précise des chunks — identifie à la fois les offsets de début et de fin de chaque chunk selon la norme du format, minimisant les faux positifs.
• Extraction de chunks inconnus — extrait et signale les données qui ne correspondent à aucun format connu, en identifiant automatiquement le remplissage nul / 0xFF.
• Analyse d'entropie — calcule l'entropie de Shannon et la probabilité du chi-carré pour les chunks inconnus, utile pour repérer des données chiffrées ou compressées.
• Rapports JSON de métadonnées — génère des rapports structurés avec les offsets des chunks, tailles, entropie, propriétaire des fichiers, permissions, horodatages, etc.
• Multi-traitement — utilise tous les cœurs CPU disponibles par défaut pour une extraction rapide.
• Système extensible de plugins — écrivez des gestionnaires de format et des extracteurs personnalisés et chargez-les à l'exécution avec --plugins-path.
• Aucun privilège élevé requis — s'exécute en toute sécurité comme un utilisateur normal.
• Éprouvé par des tests — testé par fuzzing sur un large corpus d'images de firmware ; repose sur des dépendances auditées et épinglées.

---

Installation

pip (recommandé pour la plupart des utilisateurs)

pip install unblob

Installez ensuite les outils d'extraction externes nécessaires. Sur Ubuntu/Debian :

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

Pour la prise en charge de SquashFS, installez également 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

Vérifiez que tous les extracteurs sont disponibles :

unblob --show-external-dependencies

Docker (tout compris)

L'image Docker regroupe tous les extracteurs — aucune configuration supplémentaire nécessaire :

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

Remarque : Les répertoires montés doivent appartenir au même uid:gid. Sur les systèmes multi-utilisateurs, ajoutez -u $UID:$GID à la commande.

Kali Linux

sudo apt install unblob

Nix

nix profile install nixpkgs#unblob

Ou ajoutez-le à votre configuration NixOS/home-manager — voir la documentation d'installation pour des exemples de flake et overlay.

Depuis les sources

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

Nécessite Python ≥ 3.10, uv et une chaîne d'outils Rust (pour les extensions compilées).

---

Utilisation

Ligne de commande

Extraire un fichier (la sortie va par défaut dans <filename>_extract/) :

unblob firmware.bin

Spécifier un répertoire de sortie personnalisé :

unblob -e /tmp/output firmware.bin

Générer un rapport JSON de métadonnées :

unblob --report report.json firmware.bin

Limiter la profondeur de récursion et activer l'analyse d'entropie :

unblob -d 5 -n 2 firmware.bin

Ignorer les fichiers correspondant à un préfixe de signature magique :

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

Charger un plugin de gestionnaire personnalisé :

unblob -P ./myplugins/ firmware.bin

Référence complète de l'interface en ligne de commande

Usage: unblob [OPTIONS] FILE

Options:
  -e, --extract-dir DIRECTORY     Extraire les fichiers dans ce répertoire.
  -f, --force                     Forcer l'extraction même si les sorties existent déjà.
  -d, --depth INTEGER             Profondeur de récursion (par défaut : 10).
  -n, --entropy-depth INTEGER     Profondeur de calcul de l'entropie (par défaut : 1 ; 0 = désactivé).
  -P, --plugins-path PATH         Charger des plugins depuis le chemin fourni.
  -S, --skip-magic TEXT           Ignorer les fichiers avec un préfixe magique donné.
  -p, --process-num INTEGER       Nombre de processus workers parallèles (par défaut : nombre de CPU).
  --report PATH                   Écrire un rapport JSON de métadonnées dans ce fichier.
  -k, --keep-extracted-chunks     Conserver les chunks extraits sur le disque.
  --delete-extracted-files TEXT   Supprimer les fichiers intermédiaires après extraction.
  -v, --verbose                   Augmenter la verbosité (-v, -vv, -vvv).
  --show-external-dependencies    Lister les outils externes requis et leur statut.
  -h, --help                      Afficher ce message et quitter.

API Python

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"))

Pour également écrire un rapport JSON :

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

ExtractionConfig accepte les mêmes options que l'interface en ligne de commande : max_depth, process_num, skip_magic, force_extract, keep_extracted_chunks, etc. Voir la référence de l'API pour la liste complète.

---

Tests

unblob utilise pytest. Les fixtures des tests d'intégration sont stockées dans Git LFS.

# Installer Git LFS (configuration unique)
git lfs install

# Installer toutes les dépendances de développement
uv sync --all-extras --dev

# Exécuter la suite complète de tests
uv run pytest tests/ -v

---

Documentation

La documentation complète est disponible sur https://unblob.org :

• Installation
• Guide utilisateur
• Formats pris en charge
• Référence de l'API
• Guide de développement — écrire des gestionnaires, extracteurs et plugins personnalisés
• Guide de contribution

---

Contribuer

Les contributions sont les bienvenues ! Si vous souhaitez ajouter la prise en charge d'un nouveau format ou améliorer un format existant :