karankantaria/binvizأداة تصوّر وفرز ثنائي — أسطح الإنتروبيا وفئات البايت وهيلبرت، ومخططات النقاط ورسوم تدفق التحكم عبر نموذج مساحة عناوين مشترك واحد.
أداة تصور وتحليل أولي للملفات الثنائية: عروض تفاعلية مترابطة (الإنتروبيا، المخططات البيانية، أسطح الصور/النقاط، رسوم التحكم في التدفق) فوق نموذج واحد مشترك لمساحة العناوين.
pipx install binviz && binviz serve
افتح ملفًا وكل عرض ينظر إلى نفس مساحة العناوين. حدد نطاقًا في أحدها والباقي يتبعه — الهدف هو الإجابة على سؤال "ما هذه المنطقة" بالنظر إليها بعدة طرق في وقت واحد.
binviz model يحلل ELF/PE/Mach-O عبر LIEF إلى مناطق ورموز وربط إزاحة↔عنوان افتراضي، مع إظهار الفجوات والتراكبات. المدخلات التالفة تتراجع إلى نموذج خام بدلاً من الفشل.binviz triage يقول كيف يبدو الملف ولماذا؛ في الواجهة كل نتيجة تنقر للوصول إلى البايتات التي اشتقت منها.الواجهة هي خمس مساحات عمل — نظرة عامة، بايتات، أنماط، كود، والكل — فوق نفس التحديد. تحليل ثابت فقط: العينات تُحلل، ولا تُنفذ أبدًا.
مُنتجة بنفس الكود الذي ترسم به الواجهة، مباشرة من سطر الأوامر — أعد توليدها بـ python docs/make_plates.py.
| ملف ثنائي ثابت | نفس البرنامج، مضغوط بـ UPX |
|---|---|
 |  |
| الكود والسلاسل والحشو تنفصل إلى مناطق مرئية. | البنية تنهار إلى ضوضاء موحدة — بصمة الضغط. |
 |  |
| إنتروبيا النوافذ تبقى نطاقية ومنخفضة. | مسطحة وعالية، حتى كعب فك الضغط. |
| خطوة الصف الصحيحة | خطوة الصف الخاطئة |
|---|---|
 |  |
نفس البايتات، رقم واحد مختلف. لهذا يوجد مقترح الخطوة: خطوة الصف الخاطئة تحول الصورة الفوتوغرافية إلى ضوضاء قطرية، فتستنتج أنه لا توجد صورة فوتوغرافية.
ARCHITECTURE.md هو كيف يتم تجميعها: ما يُشحن، العلامة التجارية التي يرثها كل سطح، الاتفاقيات التي يجب أن يتبعها أي شاشة جديدة، والقيود المتعمدة. SECURITY.md هو الموقف الأمني.
python -m venv .venv
# -c يثبت الإصدارات الدقيقة التي تعمل بها المجموعة؛ pyproject.toml
# ينشر نطاقات، لذا بدونها تحصل على ما يُحل اليوم
.venv/Scripts/pip install -e ".[dev]" -c constraints-dev.txt # POSIX: .venv/bin/pip
# بناء مجموعة البيانات الحقيقية (يستخدم zig cc من حزمة ziglang pip؛
# يحتاج UPX في PATH، أو في $UPX، أو مفكوكًا في corpus/tools/upx-*/)
make -C corpus # أو: python corpus/build.py
# العتبات مقاسة، وليست مشفرة أبدًا (انظر ARCHITECTURE.md §2.1)
python corpus/calibrate.py # يكتب corpus/calibration.json
pytest # مجموعة الاختبارات الوظيفية
pytest -m perf -s # أهداف أداء 100 ميجابايت
binviz probe corpus/out/hello_O2
binviz model corpus/out/hello_upx
binviz signal corpus/out/hello_upx --name entropy_4096 --png out.png
binviz hist corpus/out/ramp16.bin --n 2 --dtype u16le --png bigram.png
# الأسطح: -p يمرر معاملات السطح
binviz surface corpus/out/hello_static --name hilbert -p mode=byteclass --png h.png
binviz surface corpus/out/rgb_raw.bin --name image -p mode=rgb8 -p width=320 --png i.png
binviz surface corpus/out/repeats.bin --name dotplot -p mode=exact --png d.png
binviz stride corpus/out/bayer_raw.bin --mode bayer_RGGB_RGB_12
# الكود
binviz disasm corpus/out/hello_O2 --limit 20
binviz functions corpus/out/hello_static --sort size
binviz cfg corpus/out/hello_O2 --func main --dot main.dot
# الحكم، ولماذا
binviz triage corpus/out/hello_upx
binviz serve # 127.0.0.1:8000
يطبع عنوان URL يحتوي رمز جلسة — افتحه. كل مسار /api يتطلب الرمز، لأن "يستمع فقط على localhost" ليس دفاعًا ضد صفحة ويب في تبويب آخر، تصل إلى 127.0.0.1 مثل أي أصل آخر. SECURITY.md يحتوي المنطق.
الوصول إلى الملفات محصور في --root (الافتراضي: دليل العمل)، لذا تُرفض المسارات خارجه.
كل الأربعة لها علم ومتغير بيئة، وكل الأربعة موجودة لمنع مستدعي محلي من استهلاك أكثر مما قصدت. الافتراضات مختارة لجهاز محمول؛ ارفعها إذا كان جهازك أكبر.
| العلم | البيئة | الافتراضي | ما يحدده |
|---|---|---|---|
--max-cache BYTES | BINVIZ_MAX_CACHE | 5 جيجابايت | الحجم الإجمالي للتحليلات المخزنة. بعد ذلك، تُطرد الإدخالات الأقل استخدامًا مؤخرًا — ولا يُطرد أبدًا ما يُحلل أو يُعرض. |
--max-upload BYTES | BINVIZ_MAX_UPLOAD | 8 جيجابايت | أكبر رفع مقبول. |
--max-analyses N | — | 4 | التحليلات المتزامنة؛ بعدها يُرجع /api/open 503. |
--root DIR | — | cwd | الدليل الذي قد يقرأ منه الخادم الملفات. |
التحليلات مخزنة تحت ~/.cache/binviz (أو $BINVIZ_CACHE)، بمفتاح تجزئة المحتوى، لذا إعادة فتح ملف ثنائي فورية. ارفع --max-cache إذا كنت تفضل الاحتفاظ بالمزيد؛ ذاكرة التخزين المؤقت آمنة للحذف يدويًا في أي وقت — أسوأ حالة هي أن إعادة الفتح التالية تعيد التحليل.
أعلام أخرى: --token لتثبيت رمز عبر عمليات إعادة التشغيل (مفيد مع وكيل تطوير Vite، الذي يقرأ BINVIZ_TOKEN)، --port، --cache، و--no-auth لـ CI. --no-auth يطبع لافتة تخبرك بما أطفأه؛ لا تستخدمه على جهاز تشاركه.
pip install "binviz[app]"
binviz app # نافذة أصلية؛ --browser لمتصفحك
نفس الخادم، نفس الرمز، نفس تقييد --root مثل binviz serve — الفرق الوحيد هو ما يعرضه. بدون تثبيت pywebview، يفتح binviz app متصفحك بدلاً من ذلك.