unblob

准确、快速且易于使用的二进制blob提取套件。

unblob 解析未知的二进制 blob，支持 78 种以上的归档、压缩和文件系统格式，递归提取其内容，并雕刻出未知块。它是提取、分析和逆向工程固件镜像的理想伴侣。

演示

demo

特性

支持 78 种以上格式 — 包括归档、压缩流和文件系统，如 SquashFS、JFFS2、UBI/UBIFS、ext、CPIO、ZIP、7-Zip、gzip、XZ、LZMA、LZ4 等。查看完整列表。
递归提取 — 递归提取嵌套容器，直到可配置的深度（默认：10 层）。
精确的块检测 — 根据格式标准识别每个块的起始和结束偏移，最大限度减少误报。
未知块雕刻 — 雕刻并报告不匹配任何已知格式的数据，自动识别空/0xFF 填充。
熵分析 — 计算未知块的香农熵和卡方概率，有助于发现加密或压缩数据。
JSON 元数据报告 — 生成结构化报告，包含块偏移、大小、熵、文件所有权、权限、时间戳等。
多进程处理 — 默认使用所有可用的 CPU 核心以实现快速提取。
可扩展的插件系统 — 编写自定义格式处理程序和提取器，并通过 --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       并行工作进程数（默认：CPU 数量）。
  --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 参考
开发指南 — 编写自定义处理程序、提取器和插件
贡献指南

贡献

欢迎贡献！如果您想添加对新格式的支持或改进现有格式：

打开一个问题描述该格式（十六进制转储、规范链接和示例文件会非常有帮助）。
阅读开发指南了解如何编写处理程序和提取器。
Fork 此仓库，实现您的更改，然后发起 Pull Request。

如果您只是需要一个格式得到支持而不想自己实现，请打开一个问题——我们会考虑添加它。

更多详情请参见 CONTRIBUTING。

许可证

unblob 采用 MIT 许可证。

unblob

最受欢迎

unblob

演示

特性

安装

pip（推荐大多数用户使用）

Docker（一站式解决方案）

Kali Linux

Nix

从源码安装

用法

命令行

完整 CLI 参考

Python API

测试

文档

贡献

许可证