yilongmd/zafrida-uiنافذة أداة Frida UI داخل PyCharm / JetBrains IDEs.
中文 | [English](https://github.com/yilongmd/zafrida-ui/blob/main/README.en-US.md)
ZAFrida UI - إضافة Frida لـ PyCharm
===============
الإصدار الحالي: 0.3.8
[](LICENSE)
[](https://github.com/yilongmd/zafrida-ui)
[](https://plugins.jetbrains.com/)
[](https://github.com/yilongmd/zafrida-ui)
## أبرز تحديثات 0.3.8
- في لوحة Session تم فصل «الجهاز» و«وضع الاتصال» إلى سطرين مستقلين للاختيار: سطر Device يعرض الأجهزة الحقيقية فقط، وسطر Mode لاختيار USB / Remote / Gadget ونقطة النهاية. عمليات إعادة توجيه منفذ adb عبر الاسترجاع (loopback) في وضعي Remote/Gadget، وForce Stop، وOpen App تعمل دائمًا على الهاتف المحدد حاليًا، ولم تعد تستخدم جهازًا سابقًا بالخطأ.
- عند فتح الأجهزة لأول مرة وتحديثها يتم تشغيل خادم adb تلقائيًا إن لم يكن قيد التشغيل، دون الحاجة لتنفيذ `adb devices` يدويًا.
- عند عدم اتصال جهاز محفوظ بالإنترنت يظهر عنصر نائب «غير متصل» ويتم اعتراض العمليات المرتبطة به؛ وعند اتصال جهاز USB واحد فقط يتم التبديل إليه تلقائيًا مع تنبيه في Console.
- أسفل سطر Mode يظهر مسار adb/frida المنفَّذ فعليًا؛ وفي وضع Gadget يكون اسم حزمة Target للقراءة فقط لكنه قابل للتحديد والنسخ.
- أُضيف إلى `/state` في HTTP API حقل `connection` بنتيجة التحليل؛ ولا يزال `device-select --host` متاحًا لكنه مهمَل، ويُرجى استخدام `mode-set --host/--port` لنقاط النهاية.
## أبرز تحديثات 0.3.7
- يمكن لكل ZAFrida Project اختيار بيئة Python/Frida بشكل مستقل أو مشاركتها، ويُستخدم افتراضيًا مفسّر مشروع PyCharm الحالي، مع دعم البيئات المحلية venv وConda وuv وPoetry وPipenv وHatch وغيرها.
- أُعيد تصميم واجهة Session وProject Settings، مع عرض كامل لمعلومات إصدارات الإضافة وPython وFrida، وتحسين التكيّف ولوحة السجلات القابلة للسحب وحالة الجلسة.
- دعم كامل لـ `.js` / `.ts`، وFrida 16/17، والتبديل بين بيئات مشاريع متعددة، وسير عمل الاتصال الثلاثة USB وRemote وGadget.
- تعزيز HTTP API المحلي وCLI ومهارة (Skill) الصينية بقدرات استعادة الجهاز وانتظار الجلسة والسجلات التراكمية؛ وإزالة طبقة تكييف MCP المكررة وغير المستقرة.
مقدمة المشروع
-----------------------------------
<h3 align="center">أداة Frida برسومية مصممة خصيصًا لـ PyCharm/IntelliJ</h3>
ZAFrida UI هي إضافة تشغيل رسومية لـ Frida مدمجة في PyCharm وسلسلة JetBrains IDE. تهدف إلى حل مشكلات تعقيد عمليات Frida عبر سطر الأوامر وفوضى إدارة السكربتات، وتوفر مجموعة كاملة من **واجهات التفاعل الرسومية** لإدارة الأجهزة والعمليات والسكربتات والسجلات.
تكمن الميزة الجوهرية في نظام إدارة القوالب **«بنمط مربعات الاختيار»**: يمكن للمستخدم عبر التحديد/إلغاء التحديد إدراج مقاطع الكود ديناميكيًا في السكربت الرئيسي أو تحويلها إلى تعليقات، مما يحقق تجميع سكربتات Hook **«بنمط المكعبات»**. كما تتضمن الإضافة نظام **إدارة مشاريع** كاملًا (`zafrida-project.xml`) يدعم التبديل السريع بين إعدادات أجهزة وبيئات متعددة.
لا تحل ZAFrida محل Frida، بل تعمل كواجهة رسومية قوية لـ `frida-tools`، وتتكامل بسلاسة مع بيئة Python وFrida الحالية لديك.
**Wiki المبسّط**: [ZAFrida UI Wiki المبسّط (BBS)](https://github.com/yilongmd/zafrida-ui/blob/main/zafrida_ui_wiki_bbs_zh.md) (هذا هو الـ Wiki الأبسط)
**دليل الاستخدام المفصّل**: [ZAFrida UI دليل الاستخدام المفصّل Wiki](https://github.com/yilongmd/zafrida-ui/blob/main/ZAFridaUI_Wiki_zh.md)
## عرض توضيحي
البدء السريع
-----------------------------------
1. **تثبيت الإضافة**: ابحث عن "ZAFrida" في سوق إضافات IDE أو ثبّتها من القرص.
2. **تهيئة البيئة الافتراضية**: يُستخدم افتراضيًا Python Interpreter لمشروع PyCharm الحالي؛ وفي `Settings` العام -> `Tools` -> `ZAFrida` تُحفظ فقط القيم الافتراضية لأسماء/مسارات الأدوات.
3. **إنشاء مشروع**: انقر بزر الفأرة الأيمن في عرض المشروع -> `New Frida Project`.
* إذا احتاج هذا المشروع إلى إصدار Frida مختلف، افتح ZAFrida `Project Settings`، واختر مفسّر Python أو دليل البيئة ثم انقر `Test`.
4. **كتابة/اختيار السكربت**: اختر `agent.js` أو `agent.ts` في لوحة Run.
5. **تصحيح Hook**:
* الاتصال بالجهاز (USB أو Remote أو Gadget).
* اختيار العملية أو اسم الحزمة الهدف.
* النقر على **Run**.
6. **استخدام القوالب**: انتقل إلى تبويب `Templates`، وحدّد وظائف Hook التي تحتاجها (مثل "SSL Pinning Bypass")، وسيُدرج الكود تلقائيًا في سكربتك.
7. **أتمتة Skills (اختياري)**: معطّلة افتراضيًا. انتقل إلى `Settings/Preferences -> ZAFrida -> Skills HTTP API`، وبعد تحديد `Enable Skills` يمكن تشغيل API المحلي تلقائيًا (أو يدويًا عبر `Start/Stop`)، ومواقع CLI والقوالب:
* المهارة وCLI الرئيسي: `skills-template/zafrida-http-control/`
* مشغّل متوافق مع المسار القديم: `skills-cli/zafrida_skill_cli.py`
رمز QR لمجموعة التواصل
-----------------------------------
<img src="https://assets.kitploit.com/production/public/readmes/11475/af2e178a9eee68ad3cbdf0c5b002b39f4c18f0128b73575324967291f19eeddc.jpg" alt="ZAFrida与逆向交流群二维码" width="260" />
الميزات الوظيفية
-----------------------------------
* **إدارة الأجهزة والعمليات**
دمج `frida-ls-devices` و`frida-ps`، مع دعم تحديث قائمة الأجهزة بنقرة واحدة، وعرض العمليات قيد التشغيل، أو التطبيقات العاملة، أو التطبيقات المثبّتة.
* **اتصال متعدد الأوضاع**
دعم كامل لأوضاع **USB / Remote / Gadget**، مع دعم Host وPort مخصصين للاتصال عن بُعد، دون الحاجة لتجميع معاملات سطر أوامر معقدة يدويًا.
* **تشغيل السكربت التفاعلي (Run / Attach)**
* دعم إجراءي التنفيذ **Run (Spawn افتراضيًا)** و**Attach**، بدلًا من مجرد «تبديل الوضع».
* دعم **Force Stop** لإيقاف التطبيق الهدف قسريًا.
* إخراج سجلات مدمج في وحدة التحكم، مع حفظ السجلات تلقائيًا في دليل المشروع `zafrida-logs/`.
* **قائمة النقر بزر الفأرة الأيمن في محرر JS / TypeScript (مهم)**
* بالنقر بزر الفأرة الأيمن داخل منطقة تحرير ملف Frida `.js` أو `.ts`، يمكن الاختيار مباشرة:
* **Run Frida Script**: تنفيذ الملف الحالي كسكربت رئيسي (Spawn افتراضيًا).
* **Attach Frida Script**: حقن الملف الحالي كسكربت إضافي في العملية الهدف قيد التشغيل.
* قبل التنفيذ يتم حفظ الملف الحالي تلقائيًا، والتبديل تلقائيًا إلى ZAFrida Project الذي ينتمي إليه السكربت.
* مناسب لـ PoC السريع، والتحقق من Demo، ووضع Gadget، أو الحقن الفوري في عملية قيد التشغيل.
* **اختصارات لوحة المفاتيح**:
* Windows / Linux: `Ctrl + Alt + S`
* macOS: `⌘ + ⌥ + S`
* **إدراج Snippets من قائمة النقر بزر الفأرة الأيمن في المحرر**
* توفير **ZAFrida Frida Snippets** في قائمة النقر بزر الفأرة الأيمن في محرر JS / TypeScript.
* إدراج مقاطع كود Frida الشائعة بنقرة واحدة، مثل:
* بنية تغليف `Java.perform`
* قالب Hook لطرق Java
* `Interceptor.attach` لـ Native Hook
* تتبع عملية الإدراج IDE WriteCommandAction، مع إمكانية التراجع/الإعادة بأمان.
* **نظام القوالب الديناميكي (الابتكار الجوهري)**
* قوالب Hook مدمجة شائعة لأندرويد / iOS (مثل SSL Pinning Bypass، Method Hook، Native Hook).
* **تحكم بمربعات الاختيار**: التحديد يُدرج الكود، وإلغاء التحديد يحوّل الكود تلقائيًا إلى تعليق، دون حاجة للحذف أو التعديل اليدوي.
* دعم قوالب مخصصة، مع معاينة مباشرة لكود القالب داخل IDE.
* **تصميم منفصل لـ Run Script + Attach Script**
* دعم وجود **Run Script** رئيسي و**Attach Script** مستقل معًا.
* مناسب لفصل «Hook في مرحلة الإقلاع» عن «منطق الحقن في مرحلة التشغيل»، مما يسهّل التصحيح المعقد والصيانة طويلة الأمد.
* **تهيئة بنمط المشروع (ZAFrida Project)**
* إدخال مفهوم ZAFrida Project لحفظ الجهاز والهدف والسكربت وAttach Script ومعاملات الاتصال كسياق عمل كامل.
* دعم في Project View:
* `New Frida Project` لإنشاء مشروع جديد
* `Select Frida Project` للتبديل السريع للمشروع النشط حاليًا
* `Load Frida Project` لاستيراد دليل مشروع موجود
* بعد تبديل المشروع تُستعاد حالة الواجهة والإعدادات تلقائيًا.
* **تحليل ذكي لبيئة Python / Frida**
* يُحلّل افتراضيًا Python SDK لمشروع PyCharm الحالي؛ ويمكن لكل ZAFrida Project تجاوز المفسّر أو دليل البيئة بشكل مستقل.
* دعم بيئات system/pyenv المحلية، وvenv/virtualenv، وConda، وuv، وPoetry، وPipenv، وHatch.
* يمكن لعدة ZAFrida Projects اختيار المسار نفسه لمشاركة البيئة، دون نسخ venv؛ مناسب لصيانة بيئتي Frida 16/17 بشكل منفصل.
* عند غياب `frida-tools` من بيئة IDE الحالية أو بيئة المشروع المحددة صراحةً يظهر خطأ مباشر، ولن يتم استخدام إصدار آخر من PATH النظام بصمت؛ ويعرض `Test` إصدار Frida الفعلي.
* لا يمكن حاليًا استخدام Python Interpreter عن بُعد عبر SSH أو Docker أو Docker Compose أو WSL في عملية Frida الفرعية المحلية.
* **Frida 17 / TypeScript**
* اختيار الملفات، والنقر بزر الفأرة الأيمن Run/Attach، وSnippets تدعم `.js` / `.ts`؛ ويقوم REPL في Frida 17 بترجمة `-l agent.ts` تلقائيًا.
* تم ترحيل القوالب المدمجة إلى واجهات Module/NativePointer الحديثة في Frida 17، مع الحفاظ على توافق بيئات Frida 16 الشائعة.
* يحمل REPL في frida-tools جسور Java/ObjC القياسية للتوافق؛ وعند استخدام `import` لوحدات npm/طرف ثالث ينبغي إدارة التبعيات عبر `frida-create -t agent` أو ما يعادله.
* **واجهة الأتمتة المحلية Skills**
* يدعم Skills HTTP API المحلي (معطّل افتراضيًا) اكتشاف القدرات، وبيئة المشروع/Python، والأجهزة والعمليات، وRun/Attach، وقائمة السجلات التاريخية، وقراءة السجلات التراكمية المعتمدة على مؤشر البايت.
* تتضمن المهارة تدفق استعادة محدودًا `wait-device` / `wait-session`، وتميّز بين القراءات القابلة لإعادة المحاولة بأمان والعمليات ذات الآثار الجانبية غير القابلة للإعادة التلقائية.
* طريقة التفعيل: `Settings/Preferences -> ZAFrida -> Skills HTTP API`، ثم تحديد `Enable Skills`.
* CLI والقوالب المرافقة:
* `skills-template/zafrida-http-control/` (المهارة الرئيسية وCLI)
* `skills-cli/zafrida_skill_cli.py` (مشغّل متوافق مع المسار القديم)
سيناريوهات الاستخدام
-----------------------------------
ZAFrida UI مناسبة لجميع سيناريوهات الهندسة العكسية باستخدام Frida، خاصةً:
* اختبار اختراق وتحليل عكسي لتطبيقات أندرويد / iOS.
* عمليات التصحيح التي تتطلب تبديلًا متكررًا بين سكربتات Hook مختلفة.
* المهندسين المعتادين على استخدام IDE (PyCharm/IDEA) للتطوير المختلط بـ Python وJavaScript وTypeScript.
الوثائق التقنية
-----------------------------------
- **متطلبات البيئة**:
- IntelliJ IDEA أو PyCharm (يُفضّل 2024.3+)
- Python3 و`frida-tools` مثبّتان محليًا (`pip install frida-tools`)
- التأكد من وجود `frida` و`frida-ps` و`frida-ls-devices` في PATH النظام أو تحديد مساراتها في إعدادات الإضافة.
- **الإبلاغ عن المشكلات**: [Github Issues](https://github.com/yilongmd/zafrida-ui/issues)
تشغيل المشروع
-----------------------------------
1. استنساخ الكود المصدري: `git clone https://github.com/yilongmd/zafrida-ui.git`
2. افتح المشروع باستخدام IntelliJ IDEA.
3. شغّل مهمة Gradle `runIde` لبدء بيئة التصحيح.
واجهات النظام
-----------------------------------
##### الواجهة الرئيسية ولوحة التشغيل (Run Panel)
> توفر اختيار الجهاز، واختيار السكربت، وتهيئة وضع التشغيل، وإخراج وحدة التحكم.
##### إدارة القوالب الديناميكية (Template Panel)
> على اليسار اختيار الفئة، وفي الوسط تحديد القالب، وعلى اليمين معاينة مباشرة للكود. تتحكم مربعات الاختيار مباشرةً في تفعيل محتوى السكربت من عدمه.
##### واجهة الإعدادات (Settings)
> تدعم تخصيص مسارات أدوات Frida، وعنوان الاتصال عن بُعد، وإعدادات السجلات.
##### معالج إنشاء المشروع
> إنشاء هيكل مشروع Frida قياسي بسرعة.
البنية التقنية
-----------------------------------
#### بيئة التطوير
- اللغة: Java 21, Java، وسكربتات البناء تستخدم Gradle Kotlin DSL
- الإطار: IntelliJ Platform SDK
- أداة البناء: Gradle
- التبعيات: `frida` `frida-tools` (Python environment)
شكر وتقدير
-----------------------------------
شكر خاص للخبراء التالية أسماؤهم على دعمهم لقوالب سكربتات Frida JS لهذا المشروع:
* **小佳**
* **Lane**
* **迷人**
لمزيد من المساهمين ومعلومات الشكر راجع: [CONTRIBUTORS.md](https://github.com/yilongmd/zafrida-ui/blob/main/CONTRIBUTORS.md)