Hermit

مجموعة أدوات تفاعلية لهندسة عكسية ومعالجة Hermes.

يقوم hermit بفحص وتفكيك وتصحيح بنية بايت كود Hermes (HBC)، وهو التنسيق الذي تُشحن به تطبيقات React Native شيفرة JavaScript الخاصة بها. افتح ملف .hbc، وتصفح دواله، واقرأ JavaScript المفككة، وحرّر التعليمات والسلاسل والقيم الحرفية في محرر تفاعلي، ثم اكتب ملفًا لا يزال جهاز Hermes الافتراضي يحمّله ويشغّله.

على عكس الأدوات التي تكتفي بتحليل بايت كود، أو التي تصححه في مكانه دون تغيير الأحجام، يعيد hermit تسلسل الملف بأكمله. يمكنه إدراج التعليمات وحذفها، وإعادة تحديد مواضع القفزات ومعالجات الاستثناءات، وإعادة بناء جدولي السلاسل والقيم الحرفية، وإضافة دوال جديدة، وإعادة حساب توقيع SHA-1 الختامي. الملف غير المعدّل يمر ذهابًا وإيابًا بايتًا ببايت.

• الميزات
• إصدارات HBC المدعومة
• الملفات التنفيذية الجاهزة
• البناء
• الحصول على ملف .hbc
• استخدام REPL
• التحرير والتصحيح
• أدوات سطر الأوامر
• واجهة Python البرمجية
• الاختبارات
• بنية المشروع
• القيود

الميزات

• المحلّل (Parser): الترويسة، جدول السلاسل (بما في ذلك إدخالات UTF-16 وإدخالات الفائض)، جدول الدوال (بما في ذلك ترويسات الفائض وأجسام بايت كود المشتركة)، مخازن القيم الحرفية، معالجات الاستثناءات، معلومات التصحيح، جدول مصادر الدوال.
• المفكّك (Disassembler) مع جداول أكواد تشغيل لكل إصدار (94، 95، 96).
• مخطط التدفق التحكمي (CFG) مع تصدير DOT، ومخطط الاستدعاءات، والإحالات المتبادلة للسلاسل، واستعادة وحدات Metro.
• المفكّك (Decompiler) من CFG إلى JavaScript مقروءة: if/else، الحلقات، try/catch، الإغلاقات (closures)، مصفوفات وقيم حرفية للكائنات. حتمي، دون ذكاء اصطناعي.
• مُصحّح بنيوي: حرّر جسم دالة، وغيّر قيم السلاسل والقيم الحرفية، وأضف دالة. تخفيف التفرعات، وإعادة تحديد مواضع معالجات الاستثناءات، وترويسات دوال الفائض، ومرور ذهابًا وإيابًا مطابق بايتًا ببايت.
• REPL تفاعلي (بنمط GDB) مع محرر بايت كود بملء الشاشة.

إصدارات HBC المدعومة

الإصدار	الدور
96	الهدف الأساسي. ما تستخدمه تطبيقات React Native المشحونة: RN 0.73 إلى 0.83، وRN 0.84+ مع تعطيل Hermes V1.
94، 95	مُتحقَّق منها. التنسيق مطابق لـ 96، وتختلف جداول أكواد التشغيل فقط.

التطبيقات المبنية بـ Hermes V1 (الافتراضي من RN 0.84) تُصدر HBC 98، وهو غير مدعوم بعد. ملاحظات التنسيق موجودة في doc/hbc-format/.

الملفات التنفيذية الجاهزة

تحتوي كل إصدار على أرشيفات لـ macOS وLinux، على arm64 وx86_64. لا حاجة إلى Python أو مترجم:

الأرشيف	المحتوى
hermit-<version>-<platform>.tar.gz	REPL التفاعلي: ./hermit file.hbc.
hermit-tools-<version>-<platform>.tar.gz	أدوات سطر الأوامر المستقلة hbc_*.
SHA256SUMS	المجاميع الاختبارية: shasum -a 256 -c SHA256SUMS.

tar -xzf hermit-0.1.0-macos-arm64.tar.gz
./hermit-0.1.0-macos-arm64/hermit --version

ملفات macOS الثنائية غير موقّعة. بعد التنزيل، امسح علامة الحجر الصحي مرة واحدة: xattr -dr com.apple.quarantine hermit-0.1.0-macos-arm64. تحتاج نسخ Linux إلى glibc 2.35 أو أحدث. لا يزال الأمر cfg يحتاج إلى تثبيت graph-easy.

تُنتَج الإصدارات بواسطة .github/workflows/release.yml عند دفع وسم v*، باستخدام packaging/build-release.sh، والذي يمكنك تشغيله محليًا أيضًا.

البناء

المتطلبات

• CMake 3.20 أو أحدث ومترجم C++20 (Clang أو GCC).
• Python 3.10+ مع رؤوس التطوير (مطلوبة بواسطة pybind11).
• الوصول إلى الشبكة عند أول تهيئة: يتم جلب pybind11 وCatch2 باستخدام FetchContent الخاص بـ CMake ما لم تكن مثبتة مسبقًا.
• اختياري: graph-easy للأمر cfg (cpanm Graph::Easy)، وless كأداة ترقيم صفحات له.

الترجمة

شغّل كل شيء من هذا الدليل (الدليل الذي يحتوي على CMakeLists.txt):

cmake -B build
cmake --build build -j

هذا يبني مكتبة libhbc الثابتة، ووحدة Python _libhbc (في build/bindings/)، والأدوات سطر الأوامر (في build/tools/) واختبارات الوحدة. لا يحتاج REPL سوى وحدة Python:

cmake --build build --target _libhbc

يمكن استبعاد الأدوات والاختبارات من عملية البناء، على سبيل المثال لإصدار ما:

cmake -B build -DCMAKE_BUILD_TYPE=Release -DHERMIT_BUILD_TOOLS=OFF -DHERMIT_BUILD_TESTS=OFF

أعد البناء باستخدام الأمر نفسه بعد كل تغيير في core/ أو bindings/.

macOS: إذا فشل الربط بخطأ يتعلق بـ SDK مشوّه، فوجّه البناء إلى SDK كامل، على سبيل المثال SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX26.5.sdk cmake --build build.

بيئة Python

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

الوحدة _libhbc غير مثبّتة في البيئة الافتراضية. أضف دليل البناء الخاص بها إلى PYTHONPATH كلما شغّلت hermit:

export PYTHONPATH=$PWD/build/bindings:$PYTHONPATH

الحصول على ملف .hbc

يُشحن تطبيق React Native حزمته كملف عادي:

المنصة	الموقع داخل الحزمة
Android (.apk، ملف zip)	assets/index.android.bundle
iOS (.ipa، ملف zip)	Payload/<App>.app/main.jsbundle

إذا بدأ الملف بالبايتات C6 1F BC 03 C1 03 19 1F، فهو bytecode خاص بـ Hermes. لا يفتح REPL إلا الملفات ذات الامتداد .hbc، لذا أعد تسميته:

unzip -p app.apk assets/index.android.bundle > app.hbc
xxd app.hbc | head -1      # c61f bc03 c103 191f ...

حلّل فقط التطبيقات المسموح لك بدراستها، مثل تطبيقاتك الخاصة، أو التطبيقات مفتوحة المصدر لأغراض البحث.

بناء حزم اختبار من المصدر

للحصول على مدخلات صغيرة ومضبوطة، ترجم JavaScript أو TypeScript باستخدام مترجم Hermes الذي يُصدر HBC 96 (على سبيل المثال hermesc من react-native 0.73 إلى 0.83، ضمن node_modules/react-native/sdks/hermesc/):

hermes -emit-binary -g0 -out hello.hbc hello.js     # -g0: no debug info

تُؤتمت حزمة seeder/ هذه العملية للبرامج النموذجية في seeder/samples/ وتكتب النتائج إلى seeder/corpus/:

.venv/bin/python -m seeder.compile                       # all samples
.venv/bin/python -m seeder.compile --g0 seeder/samples/loop_sum.js
.venv/bin/python -m seeder.compile --debug seeder/samples/greeting.js

--g0 يكتب <name>_g0.hbc بدون معلومات التصحيح، بينما --debug يكتب <name>_g.hbc مع معلومات التصحيح الكاملة. تحتاج عينات .ts إلى tsc في PATH لديك؛ يُؤخذ المترجم من --hermes (الافتراضي hermes). يبني seeder/build-real-bundle.sh تطبيق React Native حقيقيًا مفتوح المصدر إلى ملف .hbc.

استخدام REPL

export PYTHONPATH=$PWD/build/bindings:$PYTHONPATH
.venv/bin/python -m cli.main app.hbc

بدون وسيطة ملف، يبدأ REPL فارغًا؛ استخدم open <file.hbc>. يعرض الموجّه إصدار HBC واسم الملف، مع علامة + عند وجود تغييرات غير محفوظة: [hbc v96 | app+] >. يُحفظ السجل في ~/.hermit_history وتُكمَّل الأوامر تلقائيًا بمفتاح Tab.

> info
> strings --identifiers filter:fetch
> functions
> disasm func:12
> decompile func:isPremium
> xrefs string:"api.example.com"
> edit func:isPremium
> patch patched.hbc

تُعنون الدوال بواسطة الفهرس أو الاسم (func:12، func:isPremium)، والسلاسل النصية بواسطة الفهرس أو القيمة (string:42، string:"hello")، ومواقع القيم الحرفية بواسطة الفهرس (array:7).