unblob

Suite di estrazione accurata, veloce e facile da usare per blob binari.

unblob analizza blob binari sconosciuti per oltre 78 formati di archivi, compressione e filesystem, estrae il loro contenuto in modo ricorsivo e recupera i chunk sconosciuti. È il compagno perfetto per estrarre, analizzare e fare reverse engineering di immagini firmware.

Demo

Caratteristiche

• Oltre 78 formati supportati — archivi, flussi di compressione e filesystem tra cui SquashFS, JFFS2, UBI/UBIFS, ext, CPIO, ZIP, 7‑Zip, gzip, XZ, LZMA, LZ4 e molti altri. Vedi l'elenco completo.
• Estrazione ricorsiva — estrae contenitori all'interno di contenitori fino a una profondità configurabile (default: 10 livelli).
• Rilevamento preciso dei chunk — identifica sia l'offset di inizio che di fine di ogni chunk secondo lo standard del formato, minimizzando i falsi positivi.
• Carving di chunk sconosciuti — estrae e segnala dati che non corrispondono a nessun formato noto, identificando automaticamente il padding null/0xFF.
• Analisi dell'entropia — calcola l'entropia di Shannon e la probabilità chi‑quadrato per i chunk sconosciuti, utile per individuare dati crittografati o compressi.
• Report metadati JSON — genera report strutturati con offset dei chunk, dimensioni, entropia, proprietà dei file, permessi, timestamp e altro.
• Multi‑processing — utilizza tutti i core CPU disponibili di default per un'estrazione veloce.
• Sistema di plugin estensibile — scrivi handler e estrattori personalizzati e caricali a runtime con --plugins-path.
• Nessun privilegio elevato richiesto — viene eseguito in sicurezza come utente normale.
• Testato sul campo — testato con fuzzing su un ampio corpus di immagini firmware; si basa su dipendenze verificate e bloccate.

Installazione

pip (consigliato per la maggior parte degli utenti)

pip install unblob

Poi installa gli strumenti di estrazione esterni richiesti. Su Ubuntu/Debian:

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

Per il supporto a SquashFS, installa anche 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

Verifica che tutti gli estrattori siano disponibili:

unblob --show-external-dependencies

Docker (batterie incluse)

L'immagine Docker include tutti gli estrattori — nessuna configurazione aggiuntiva necessaria:

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

Nota: Le directory montate devono essere di proprietà dello stesso uid:gid. Su sistemi multiutente, aggiungi -u $UID:$GID al comando.

Kali Linux

sudo apt install unblob

Nix

nix profile install nixpkgs#unblob

Oppure aggiungilo alla tua configurazione NixOS/home‑manager — vedi la documentazione di installazione per esempi flake e overlay.

Dal sorgente

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

Richiede Python ≥ 3.10, uv e un toolchain Rust (per le estensioni compilate).

Utilizzo

Riga di comando

Estrai un file (l'output va in <filename>_extract/ di default):

unblob firmware.bin

Specifica una directory di output personalizzata:

unblob -e /tmp/output firmware.bin

Genera un report metadati JSON:

unblob --report report.json firmware.bin

Limita la profondità di ricorsione e abilita l'analisi dell'entropia:

unblob -d 5 -n 2 firmware.bin

Salta file che corrispondono a un prefisso magic string:

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

Carica un plugin handler personalizzato:

unblob -P ./myplugins/ firmware.bin

Riferimento CLI completo

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

Per scrivere anche un report JSON:

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

ExtractionConfig accetta le stesse opzioni della CLI: max_depth, process_num, skip_magic, force_extract, keep_extracted_chunks e altro. Vedi il riferimento API per l'elenco completo.

Testing

unblob utilizza pytest. I fixture per i test di integrazione sono memorizzati in Git LFS.

# Installa Git LFS (configurazione iniziale)
git lfs install

# Installa tutte le dipendenze di sviluppo
uv sync --all-extras --dev

# Esegui l'intera suite di test
uv run pytest tests/ -v

Documentazione

La documentazione completa è disponibile su https://unblob.org:

• Installazione
• Guida per l'utente
• Formati supportati
• Riferimento API
• Guida allo sviluppo — scrivere handler, estrattori e plugin personalizzati
• Guida ai contributi

Contributi

I contributi sono benvenuti! Se desideri aggiungere il supporto per un nuovo formato o migliorarne uno esistente:

1. Apri un issue per descrivere il formato (hex dump, link alle specifiche e file di esempio aiutano molto).
2. Leggi la guida allo sviluppo per imparare a scrivere handler ed estrattori.
3. Forka il repository, implementa le tue modifiche e apri una pull request.

Se hai solo bisogno del supporto per un formato e non vuoi implementarlo da solo, apri un issue — valuteremo l'aggiunta.

Vedi CONTRIBUTING per maggiori dettagli.

Licenza

unblob è concesso in licenza secondo la MIT License.