unblob

مجموعة استخراج دقيقة وسريعة وسهلة الاستخدام للكتل الثنائية (binary blobs).

يقوم unblob بتحليل الكتل الثنائية غير المعروفة لـ أكثر من 78 تنسيق أرشيف، ضغط، ونظام ملفات، ويستخرج محتوياتها بشكل متكرر (recursively)، وينحت (carves) الأجزاء غير المعروفة. إنها الأداة المثالية لاستخراج وتحليل وهندسة عكسية لصور البرامج الثابتة (firmware images).

عرض توضيحي

الميزات

• 78+ تنسيق مدعوم — أرشيفات، تيارات ضغط، وأنظمة ملفات تتضمن SquashFS و JFFS2 و UBI/UBIFS و ext و CPIO و ZIP و 7-Zip و gzip و XZ و LZMA و LZ4 وغيرها الكثير. راجع القائمة الكاملة.
• استخراج متكرر (recursive extraction) — يستخرج الحاويات داخل الحاويات حتى عمق قابل للتكوين (الافتراضي: 10 مستويات).
• كشف دقيق للكتل (chunks) — يحدد كلاً من بداية ونهاية كل كتلة وفقاً لمعيار التنسيق، مما يقلل من النتائج الإيجابية الخاطئة.
• نحت الكتل غير المعروفة (unknown chunk carving) — ينحت ويبلغ عن البيانات التي لا تطابق أي تنسيق معروف، مع التعرف التلقائي على بيانات الحشو (null/0xFF).
• تحليل الإنتروبيا (Entropy analysis) — يحسب إنتروبيا شانون واحتمال مربع كاي (chi-square) للكتل غير المعروفة، مفيداً لاكتشاف البيانات المشفرة أو المضغوطة.
• تقارير JSON الوصفية — يولد تقارير منظمة تتضمن إزاحات الكتل (offsets)، الأحجام، الإنتروبيا، ملكية الملفات، الصلاحيات، الطوابع الزمنية، والمزيد.
• معالجة متعددة (multi-processing) — يستخدم جميع نوى المعالجة (CPU cores) المتاحة افتراضياً للاستخراج السريع.
• نظام إضافات قابل للتوسيع — اكتب معالجات ومستخلصات تنسيق مخصصة وقم بتحميلها أثناء التشغيل باستخدام --plugins-path.
• لا يتطلب صلاحيات مرتفعة — يعمل بأمان كمستخدم عادي.
• مُختبر في المعارك (battle-tested) — تم اختباره بالتشويش (fuzz tested) ضد مجموعة كبيرة من صور البرامج الثابتة؛ ويعتمد على تبعيات مدققة ومثبتة (pinned dependencies).

التثبيت

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

تخطي الملفات التي تطابق بادئة سحرية (magic string):

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

تحميل إضافة معالج مخصصة:

unblob -P ./myplugins/ firmware.bin

مرجع CLI كامل

Usage: unblob [OPTIONS] FILE

Options:
  -e, --extract-dir DIRECTORY     Extract the files to this directory.
  -f, --force                     Force extraction even if outputs already exist.
  -d, --depth INTEGER             Recursion depth (default: 10).
  -n, --entropy-depth INTEGER     Entropy calculation depth (default: 1; 0 = off).
  -P, --plugins-path PATH         Load plugins from the provided path.
  -S, --skip-magic TEXT           Skip files with a given magic prefix.
  -p, --process-num INTEGER       Number of parallel worker processes (default: CPU count).
  --report PATH                   Write a JSON metadata report to this file.
  -k, --keep-extracted-chunks     Keep extracted chunks on disk.
  --delete-extracted-files TEXT   Delete intermediate files after extraction.
  -v, --verbose                   Increase verbosity (-v, -vv, -vvv).
  --show-external-dependencies    List required external tools and their status.
  -h, --help                      Show this message and exit.

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. مخازن اختبارات التكامل (integration test fixtures) مخزنة في Git LFS.

# تثبيت Git LFS (إعداد لمرة واحدة)
git lfs install

# تثبيت جميع تبعيات التطوير
uv sync --all-extras --dev

# تشغيل مجموعة الاختبارات الكاملة
uv run pytest tests/ -v

التوثيق

التوثيق الكامل متاح في https://unblob.org:

• التثبيت
• دليل المستخدم
• التنسيقات المدعومة
• مرجع API
• دليل التطوير — كتابة معالجات ومستخلصات وإضافات مخصصة
• دليل المساهمة

المساهمة

المساهمات مرحب بها! إذا كنت ترغب في إضافة دعم لتنسيق جديد أو تحسين تنسيق موجود:

1. افتح issue لوصف التنسيق (تفريغ سداسي عشري (hex dumps)، روابط مواصفات، وملفات نموذجية مفيدة جداً).
2. اقرأ دليل التطوير لمعرفة كيفية كتابة المعالجات والمستخلصات.
3. قم بعمل fork للمستودع، نفذ تغييراتك، وافتح pull request.

إذا كنت تحتاج فقط إلى دعم تنسيق ولا ترغب في تنفيذه بنفسك، افتح issue — سننظر في إضافته.

راجع المساهمة لمزيد من التفاصيل.

الترخيص

unblob مرخص بموجب رخصة MIT.