unblob

Точный, быстрый и простой в использовании набор для извлечения данных из бинарных блобов.

unblob анализирует неизвестные бинарные блобы на предмет 78+ форматов архивов, сжатия и файловых систем, рекурсивно извлекает их содержимое и вырезает неизвестные фрагменты. Это идеальный инструмент для извлечения, анализа и обратного проектирования прошивок.

Демо

Возможности

• 78+ поддерживаемых форматов — архивы, потоки сжатия и файловые системы, включая SquashFS, JFFS2, UBI/UBIFS, ext, CPIO, ZIP, 7-Zip, gzip, XZ, LZMA, LZ4 и многие другие. См. полный список.
• Рекурсивное извлечение — извлекает контейнеры внутри контейнеров до настраиваемой глубины (по умолчанию: 10 уровней).
• Точное обнаружение фрагментов — определяет как начальные, так и конечные смещения каждого фрагмента в соответствии со стандартом формата, минимизируя ложные срабатывания.
• Вырезание неизвестных фрагментов — вырезает и сообщает о данных, которые не соответствуют ни одному известному формату, автоматически определяя пустые заполнители (null/0xFF).
• Анализ энтропии — вычисляет энтропию Шеннона и вероятность хи-квадрат для неизвестных фрагментов, что полезно для выявления зашифрованных или сжатых данных.
• Отчёты в формате JSON — генерирует структурированные отчёты со смещениями фрагментов, размерами, энтропией, владельцами файлов, правами доступа, временными метками и т.д.
• Многопроцессорность — по умолчанию использует все доступные ядра ЦП для быстрого извлечения.
• Расширяемая система плагинов — пишите собственные обработчики форматов и экстракторы, загружая их во время выполнения с помощью --plugins-path.
• Не требует повышенных привилегий — безопасно работает от обычного пользователя.
• Проверено в бою — протестировано с помощью фаззинга на большой коллекции образов прошивок; использует проверенные и фиксированные зависимости.

Установка

pip (рекомендуется для большинства пользователей)

pip install unblob

Затем установите необходимые внешние утилиты для извлечения. На Ubuntu/Debian:

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

Для поддержки SquashFS также установите 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

Проверьте доступность всех экстракторов:

unblob --show-external-dependencies

Docker (всё включено)

Образ Docker включает все экстракторы — никакой дополнительной настройки не требуется:

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

Примечание: Каталоги монтирования должны принадлежать одному и тому же uid:gid. В многопользовательских системах добавьте -u $UID:$GID в команду.

Kali Linux

sudo apt install unblob

Nix

nix profile install nixpkgs#unblob

Или добавьте в конфигурацию NixOS/home-manager — см. документацию по установке для примеров с flake и overlay.

Из исходников

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

Требуется Python ≥ 3.10, uv и инструментарий Rust (для скомпилированных расширений).

Использование

Командная строка

Извлечение файла (результат по умолчанию помещается в каталог <filename>_extract/):

unblob firmware.bin

Указать свой каталог для вывода:

unblob -e /tmp/output firmware.bin

Сгенерировать отчёт в формате JSON:

unblob --report report.json firmware.bin

Ограничить глубину рекурсии и включить анализ энтропии:

unblob -d 5 -n 2 firmware.bin

Пропустить файлы, соответствующие префиксу магической строки:

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

Загрузить пользовательский плагин-обработчик:

unblob -P ./myplugins/ firmware.bin

Полный справочник CLI

Usage: unblob [OPTIONS] FILE

Options:
  -e, --extract-dir DIRECTORY     Извлечь файлы в этот каталог.
  -f, --force                     Принудительное извлечение, даже если выходные данные уже существуют.
  -d, --depth INTEGER             Глубина рекурсии (по умолчанию: 10).
  -n, --entropy-depth INTEGER     Глубина расчёта энтропии (по умолчанию: 1; 0 = выкл.).
  -P, --plugins-path PATH         Загрузить плагины из указанного пути.
  -S, --skip-magic TEXT           Пропустить файлы с заданным префиксом магической строки.
  -p, --process-num INTEGER       Количество параллельных рабочих процессов (по умолчанию: количество ядер ЦП).
  --report PATH                   Записать отчёт в формате JSON в этот файл.
  -k, --keep-extracted-chunks     Сохранять извлечённые фрагменты на диске.
  --delete-extracted-files TEXT   Удалить промежуточные файлы после извлечения.
  -v, --verbose                   Увеличить уровень подробности (-v, -vv, -vvv).
  --show-external-dependencies    Вывести список необходимых внешних инструментов и их состояние.
  -h, --help                      Показать это сообщение и выйти.

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

Чтобы также записать отчёт в JSON:

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

ExtractionConfig принимает те же параметры, что и CLI: max_depth, process_num, skip_magic, force_extract, keep_extracted_chunks и другие. См. справочник API для полного списка.

Тестирование

unblob использует pytest. Фикстуры для интеграционных тестов хранятся в Git LFS.

# Установить Git LFS (однократная настройка)
git lfs install

# Установить все зависимости для разработки
uv sync --all-extras --dev

# Запустить полный набор тестов
uv run pytest tests/ -v

Документация

Полная документация доступна на https://unblob.org:

• Установка
• Руководство пользователя
• Поддерживаемые форматы
• Справочник API
• Руководство разработчика — написание собственных обработчиков, экстракторов и плагинов
• Руководство по внесению вклада

Вклад

Вклад приветствуется! Если вы хотите добавить поддержку нового формата или улучшить существующий:

1. Откройте issue, чтобы описать формат (hex-дампы, ссылки на спецификации и примеры файлов очень помогают).
2. Прочитайте руководство разработчика, чтобы узнать, как писать обработчики и экстракторы.
3. Сделайте форк репозитория, реализуйте изменения и отправьте pull request.

Если вам просто нужна поддержка формата, и вы не хотите реализовывать его самостоятельно, откройте issue — мы рассмотрим возможность его добавления.

Подробнее см. CONTRIBUTING.

Лицензия

unblob распространяется под лицензией MIT.