unblob

Suite de extracción precisa, rápida y fácil de usar para blobs binarios.

unblob analiza blobs binarios desconocidos para más de 78 formatos de archivo, compresión y sistema de archivos, extrae su contenido de forma recursiva y extrae fragmentos desconocidos. Es el compañero perfecto para extraer, analizar e hacer ingeniería inversa de imágenes de firmware.

Demo

Características

• Más de 78 formatos compatibles — archivos, flujos de compresión y sistemas de archivos, incluyendo SquashFS, JFFS2, UBI/UBIFS, ext, CPIO, ZIP, 7-Zip, gzip, XZ, LZMA, LZ4 y muchos más. Consulta la lista completa.
• Extracción recursiva — extrae contenedores dentro de contenedores hasta una profundidad configurable (por defecto: 10 niveles).
• Detección precisa de fragmentos — identifica tanto los desplazamientos de inicio como de fin de cada fragmento según el estándar del formato, minimizando falsos positivos.
• Extracción de fragmentos desconocidos — extrae y reporta datos que no coinciden con ningún formato conocido, identificando automáticamente rellenos nulos/0xFF.
• Análisis de entropía — calcula la entropía de Shannon y la probabilidad chi-cuadrado para fragmentos desconocidos, útil para detectar datos cifrados o comprimidos.
• Informes de metadatos en JSON — genera informes estructurados con desplazamientos de fragmentos, tamaños, entropía, propiedad de archivos, permisos, marcas de tiempo y más.
• Multiprocesamiento — utiliza todos los núcleos de CPU disponibles por defecto para una extracción rápida.
• Sistema de complementos extensible — escribe manejadores y extractores de formato personalizados y cárgalos en tiempo de ejecución con --plugins-path.
• No requiere privilegios elevados — se ejecuta de forma segura como un usuario normal.
• Probado en batalla — probado mediante fuzzing contra un gran corpus de imágenes de firmware; depende de dependencias auditadas y fijadas.

Instalación

pip (recomendado para la mayoría de usuarios)

pip install unblob

Luego instala las herramientas extractoras externas necesarias. En Ubuntu/Debian:

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

Para soporte de SquashFS, instala también 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 que todos los extractores estén disponibles:

unblob --show-external-dependencies

Docker (listo para usar)

La imagen Docker incluye todos los extractores, sin necesidad de configuración adicional:

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: Los directorios montados deben ser propiedad del mismo uid:gid. En sistemas multiusuario, agrega -u $UID:$GID al comando.

Kali Linux

sudo apt install unblob

Nix

nix profile install nixpkgs#unblob

O agrégalo a tu configuración de NixOS/home-manager; consulta la documentación de instalación para ejemplos de flake y overlay.

Desde el código fuente

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

Requiere Python ≥ 3.10, uv y un conjunto de herramientas de Rust (para las extensiones compiladas).

Uso

Línea de comandos

Extrae un archivo (la salida va a <filename>_extract/ por defecto):

unblob firmware.bin

Especifica un directorio de salida personalizado:

unblob -e /tmp/output firmware.bin

Genera un informe de metadatos en JSON:

unblob --report report.json firmware.bin

Limita la profundidad de recursión y habilita el análisis de entropía:

unblob -d 5 -n 2 firmware.bin

Omite archivos que coincidan con un prefijo de cadena mágica:

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

Carga un complemento de manejo personalizado:

unblob -P ./myplugins/ firmware.bin

Referencia completa de CLI

Uso: unblob [OPCIONES] ARCHIVO

Opciones:
  -e, --extract-dir DIRECTORY     Extrae los archivos a este directorio.
  -f, --force                     Fuerza la extracción incluso si las salidas ya existen.
  -d, --depth INTEGER             Profundidad de recursión (por defecto: 10).
  -n, --entropy-depth INTEGER     Profundidad de cálculo de entropía (por defecto: 1; 0 = desactivado).
  -P, --plugins-path PATH         Carga complementos desde la ruta proporcionada.
  -S, --skip-magic TEXT           Omite archivos con un prefijo mágico dado.
  -p, --process-num INTEGER       Número de procesos de trabajo en paralelo (por defecto: número de CPUs).
  --report PATH                   Escribe un informe de metadatos JSON en este archivo.
  -k, --keep-extracted-chunks     Mantiene los fragmentos extraídos en disco.
  --delete-extracted-files TEXT   Elimina archivos intermedios después de la extracción.
  -v, --verbose                   Aumenta la verbosidad (-v, -vv, -vvv).
  --show-external-dependencies    Lista las herramientas externas requeridas y su estado.
  -h, --help                      Muestra este mensaje y sale.

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

Para también escribir un informe JSON:

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

ExtractionConfig acepta las mismas opciones que la CLI: max_depth, process_num, skip_magic, force_extract, keep_extracted_chunks y más. Consulta la referencia de la API para la lista completa.

Pruebas

unblob usa pytest. Los fixtures de pruebas de integración se almacenan en Git LFS.

# Instalar Git LFS (configuración única)
git lfs install

# Instalar todas las dependencias de desarrollo
uv sync --all-extras --dev

# Ejecutar toda la suite de pruebas
uv run pytest tests/ -v

Documentación

La documentación completa está disponible en https://unblob.org:

• Instalación
• Guía de usuario
• Formatos compatibles
• Referencia de la API
• Guía de desarrollo — escribir manejadores, extractores y complementos personalizados
• Guía de contribución

Contribuciones

¡Las contribuciones son bienvenidas! Si deseas agregar soporte para un nuevo formato o mejorar uno existente:

1. Abre un issue para describir el formato (los volcados hexadecimales, enlaces a especificaciones y archivos de ejemplo ayudan mucho).
2. Lee la guía de desarrollo para aprender a escribir manejadores y extractores.
3. Haz un fork del repositorio, implementa tus cambios y abre una pull request.

Si solo necesitas que un formato sea compatible y no quieres implementarlo tú mismo, abre un issue; consideraremos agregarlo.

Consulta CONTRIBUTING para más detalles.

Licencia

unblob está bajo la Licencia MIT.