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 :

1. Ouvrez une issue pour décrire le format (les dumps hexadécimaux, les liens vers les spécifications et les fichiers exemples aident beaucoup).
2. Lisez le guide de développement pour apprendre à écrire des gestionnaires et extracteurs.
3. Forkez le dépôt, implémentez vos modifications et ouvrez une pull request.

Si vous avez simplement besoin qu'un format soit pris en charge et que vous ne voulez pas l'implémenter vous-même, ouvrez une issue — nous envisagerons de l'ajouter.

Consultez CONTRIBUTING pour plus de détails.

Licence

unblob est distribué sous la licence MIT.