onekey-sec/unblob모든 종류의 컨테이너 포맷에서 파일을 추출합니다.
정확하고 빠르며 사용하기 쉬운 바이너리 블롭 추출 제품군.
unblob은 알 수 없는 바이너리 블롭에서 78개 이상의 아카이브, 압축, 파일 시스템 포맷을 파싱하고, 콘텐츠를 재귀적으로 추출하며, 알 수 없는 청크를 조각냅니다. 펌웨어 이미지를 추출, 분석 및 리버스 엔지니어링하기 위한 완벽한 도구입니다.
0xFF 패딩을 자동으로 식별합니다.--plugins-path를 사용하여 런타임에 로드할 수 있습니다.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 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를 추가하세요.
sudo apt install unblob
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
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 이 메시지를 표시하고 종료합니다.
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 설치 (최초 1회)
git lfs install
# 모든 개발 의존성 설치
uv sync --all-extras --dev
# 전체 테스트 스위트 실행
uv run pytest tests/ -v
전체 문서는 https://unblob.org 에서 확인할 수 있습니다:
기여를 환영합니다! 새로운 포맷 지원을 추가하거나 기존 포맷을 개선하려면:
포맷 지원이 필요하지만 직접 구현하고 싶지 않은 경우, 이슈를 열어주세요. 추가를 고려하겠습니다.
자세한 내용은 CONTRIBUTING을 참조하세요.
unblob은 MIT 라이선스에 따라 라이선스가 부여됩니다.