unblob

Suíte de extração precisa, rápida e fácil de usar para blobs binários.

O unblob analisa blobs binários desconhecidos em 78+ formatos de arquivo, compressão e sistemas de arquivos, extrai seu conteúdo recursivamente e extrai partes desconhecidas. É o companheiro perfeito para extrair, analisar e fazer engenharia reversa de imagens de firmware.

Demonstração

Funcionalidades

• 78+ formatos suportados — arquivos, streams de compressão e sistemas de arquivos, incluindo SquashFS, JFFS2, UBI/UBIFS, ext, CPIO, ZIP, 7-Zip, gzip, XZ, LZMA, LZ4 e muitos outros. Veja a lista completa.
• Extração recursiva — extrai contêineres dentro de contêineres até uma profundidade configurável (padrão: 10 níveis).
• Detecção precisa de chunks — identifica tanto os offsets de início quanto de fim de cada chunk de acordo com o padrão do formato, minimizando falsos positivos.
• Extração de chunks desconhecidos — extrai e relata dados que não correspondem a nenhum formato conhecido, identificando automaticamente preenchimento nulo/0xFF.
• Análise de entropia — calcula a entropia de Shannon e probabilidade qui-quadrado para chunks desconhecidos, útil para detectar dados criptografados ou comprimidos.
• Relatórios de metadados JSON — gera relatórios estruturados com offsets, tamanhos, entropia, propriedade de arquivos, permissões, timestamps e mais.
• Multiprocessamento — utiliza todos os núcleos de CPU disponíveis por padrão para extração rápida.
• Sistema de plugins extensível — escreva manipuladores e extratores de formatos personalizados e carregue-os em tempo de execução com --plugins-path.
• Não requer privilégios elevados — executa com segurança como um usuário comum.
• Testado em batalha — testado por fuzzing contra um grande corpus de imagens de firmware; depende de dependências auditadas e fixadas.

Instalação

pip (recomendado para a maioria dos usuários)

pip install unblob

Em seguida, instale as ferramentas extratoras externas necessárias. No Ubuntu/Debian:

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

Para suporte a SquashFS, instale também o 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

Verifique se todos os extratores estão disponíveis:

unblob --show-external-dependencies

Docker (com tudo incluso)

A imagem Docker inclui todos os extratores — nenhuma configuração extra necessária:

docker run \
  --rm \
  --pull always \
  -v /caminho/para/dir-de-extração:/data/output \
  -v /caminho/para/arquivos:/data/input \
  ghcr.io/onekey-sec/unblob:latest /data/input/firmware.bin

Nota: Os diretórios montados devem ser de propriedade do mesmo uid:gid. Em sistemas multiusuário, adicione -u $UID:$GID ao comando.

Kali Linux

sudo apt install unblob

Nix

nix profile install nixpkgs#unblob

Ou adicione à sua configuração NixOS/home-manager — veja a documentação de instalação para exemplos com flake e overlay.

A partir do código fonte

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

Requer Python ≥ 3.10, uv e um toolchain Rust (para as extensões compiladas).

Uso

Linha de comando

Extrair um arquivo (a saída vai para <nome_do_arquivo>_extract/ por padrão):

unblob firmware.bin

Especificar um diretório de saída personalizado:

unblob -e /tmp/saida firmware.bin

Gerar um relatório de metadados JSON:

unblob --report report.json firmware.bin

Limitar a profundidade de recursão e ativar análise de entropia:

unblob -d 5 -n 2 firmware.bin

Pular arquivos que correspondam a um prefixo mágico:

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

Carregar um plugin de manipulador personalizado:

unblob -P ./meusplugins/ firmware.bin

Referência completa da CLI

Usage: unblob [OPTIONS] FILE

Options:
  -e, --extract-dir DIRECTORY     Extrair os arquivos para este diretório.
  -f, --force                     Forçar extração mesmo se as saídas já existirem.
  -d, --depth INTEGER             Profundidade de recursão (padrão: 10).
  -n, --entropy-depth INTEGER     Profundidade de cálculo de entropia (padrão: 1; 0 = desligado).
  -P, --plugins-path PATH         Carregar plugins do caminho fornecido.
  -S, --skip-magic TEXT           Pular arquivos com um determinado prefixo mágico.
  -p, --process-num INTEGER       Número de processos de trabalho paralelos (padrão: número de CPUs).
  --report PATH                   Escrever um relatório de metadados JSON para este arquivo.
  -k, --keep-extracted-chunks     Manter os chunks extraídos no disco.
  --delete-extracted-files TEXT   Excluir arquivos intermediários após a extração.
  -v, --verbose                   Aumentar a verbosidade (-v, -vv, -vvv).
  --show-external-dependencies    Listar ferramentas externas necessárias e seu status.
  -h, --help                      Mostrar esta mensagem e sair.

API Python

from pathlib import Path
from unblob.processing import ExtractionConfig, process_file

config = ExtractionConfig(
    extract_root=Path("/tmp/saida"),
    randomness_depth=1,
)

result = process_file(config, Path("firmware.bin"))

Para também escrever um relatório JSON:

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

ExtractionConfig aceita as mesmas opções da CLI: max_depth, process_num, skip_magic, force_extract, keep_extracted_chunks e mais. Veja a referência da API para a lista completa.

Testes

O unblob usa pytest. As fixtures de teste de integração são armazenadas no Git LFS.

# Instalar Git LFS (configuração única)
git lfs install

# Instalar todas as dependências de desenvolvimento
uv sync --all-extras --dev

# Executar a suíte de testes completa
uv run pytest tests/ -v

Documentação

A documentação completa está disponível em https://unblob.org:

• Instalação
• Guia do usuário
• Formatos suportados
• Referência da API
• Guia de desenvolvimento — escrevendo manipuladores, extratores e plugins personalizados
• Guia de contribuição

Contribuindo

Contribuições são bem-vindas! Se você deseja adicionar suporte a um novo formato ou melhorar um existente:

1. Abra uma issue para descrever o formato (dumps hex, links de especificações e arquivos de exemplo ajudam muito).
2. Leia o guia de desenvolvimento para aprender a escrever manipuladores e extratores.
3. Faça um fork do repositório, implemente suas alterações e abra um pull request.

Se você apenas precisa de um formato suportado e não quer implementá-lo você mesmo, abra uma issue — consideraremos adicioná-lo.

Veja CONTRIBUTING para mais detalhes.

Licença

O unblob é licenciado sob a Licença MIT.