secforce/droidgroundملعب مرن لتحديات CTF الخاصة بنظام أندرويد.
<h1 align="center">
<br>
<img src="https://assets.kitploit.com/production/public/readmes/7301/75c22abcf52c94c756ce37d77db74df73c48b6846c3aede4c8971c38e2180f65.png" alt= "droidground" width="200px">
</h1>
<p align="center">
<b>DroidGround</b>
<p>
<p align="center">
<a href="https://github.com/SECFORCE/droidground/blob/main/README.md"><img src="https://img.shields.io/badge/Documentation-complete-green.svg?style=flat"></a>
<a href="https://github.com/SECFORCE/droidground/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-GPL3-blue.svg"></a>
<a href="https://blackhat.com/eu-25/arsenal/schedule/index.html#droidground-a-flexible-playground-for-android-ctf-challenges-47803"><img src="https://raw.githubusercontent.com/secforce/droidground/HEAD/docs/blackhat-2025.svg"></a>
<br />
<a href="https://droidground.com" target="_blank">الموقع الإلكتروني</a> |
<a href="https://droidground.com/demo" target="_blank">عرض توضيحي</a>
</p>
في **تحديات CTF** التقليدية، من الشائع إخفاء الأعلام (flags) في ملفات على النظام، مما يتطلب من المهاجمين استغلال الثغرات لاستخراجها. ومع ذلك، في عالم Android، لا ينجح هذا النهج بشكل جيد. فملفات APK قابلة للتنزيل والعكس بسهولة، لذا فإن **وضع العلم على الجهاز عادةً ما يجعله تافهاً** لاستخراجه باستخدام التحليل الساكن أو حيل المحاكي. وهذا يحد بشدة من القدرة على إنشاء تحديات واقعية تركز على وقت التشغيل.
صُمم _DroidGround_ لحل هذه المشكلة.
إنها منصة مبنية خصيصاً لاستضافة تحديات اختراق Android للهواتف المحمولة في بيئة **مُتحكَّم بها** و**واقعية**، حيث يكون **المهاجمون مقيّدين بما يكفي فقط** ليتطلب منهم حل التحديات بالطريقة المقصودة.
والأهم من ذلك، قد يكون المشاركون **محبوسين داخل بيئة التطبيق**. تتيح معيارية الأداة تحديد ما إذا كان يمكن للمستخدم فتح shell، أو قراءة ملفات عشوائية، أو تحميل أدوات جانبية. يمكن إعداد كل شيء بحيث تكون الطريقة الوحيدة لاسترداد العلم هي فهم التطبيق نفسه واستغلاله.
## 📋 جدول المحتويات
- [🧭 نظرة عامة](#-نظرة-عامة)
- [✨ الميزات](#-الميزات)
- [📸 لقطات الشاشة](#-لقطات-الشاشة)
- [⚙️ الإعدادات](#️-الإعدادات)
- [🧩 حالات الاستخدام](#-حالات-الاستخدام)
- [⚙️ الاستخدام](#️-الاستخدام)
- [💡 نصائح](#-نصائح)
- [🛠 التطوير](#-التطوير)
- [🤝 المساهمة](#-المساهمة)
- [📚 الشكر والتقدير](#-الشكر-والتقدير)
- [🪪 الترخيص](#-الترخيص)
## 🧭 نظرة عامة
تُمكّن _DroidGround_ مجموعة واسعة من تحديات _Android_ التي يصعب تنفيذها بطريقة أخرى في إعدادات CTF التقليدية. على سبيل المثال، في تحدٍّ لتنفيذ التعليمات عن بُعد (RCE)، قد يتلقى اللاعبون ملف APK للتحليل المحلي. بعد اكتشاف ثغرة، يمكنهم تطوير سكربت Frida وتشغيله عبر DroidGround على الجهاز الهدف الحقيقي لاستخراج العلم من وحدة التخزين الداخلية. يمكن أن تتضمن أنواع التحديات الأخرى أنشطة مخفية، أو نوايا بث مخصصة، أو استغلال الخدمات، أو التحليل الديناميكي باستخدام أدوات محمّلة مسبقاً.
مع بث الجهاز في الوقت الفعلي، والتحكم الدقيق في الميزات، وتكامل Frida، وسكربتات الإعداد وإعادة الضبط القابلة للتخصيص، تُمكّن DroidGround منظّمي CTF من بناء تحديات Android آمنة ومرنة وواقعية تتجاوز بكثير ما هو ممكن عادةً.
## ✨ الميزات
توفر DroidGround مجموعة غنية من الميزات التي يتحكم بها الخادم.
- **شاشة الجهاز في الوقت الفعلي** (عبر `scrcpy`)، مع تحكم اختياري بالفأرة واللمس ولوحة المفاتيح
- **إعادة ضبط حالة التحدي**
- **إعادة تشغيل التطبيق / بدء النشاط / بدء الخدمة**
- **إرسال نية بث (Broadcast Intent)**
- **إيقاف التشغيل / إعادة تشغيل الجهاز**
- **تنزيل تقرير الأخطاء (bugreportz)**
- **سكربتات Frida**
- التشغيل من مكتبة محمّلة مسبقاً (وضع الحبس)
- تشغيل سكربتات عشوائية (الوضع الكامل)
- **متصفح الملفات**
- **الوصول إلى الطرفية**
- **إدارة APK**
- **عارض Logcat**
- **خادم الاستغلال** (إذا كان وضع الفرق مُفعّلاً)
جميع الميزات تقريباً **معيارية** ومُعرّفة عبر متغيرات البيئة، مما يضمن تحكماً دقيقاً في نطاق التحدي.
## 📸 لقطات الشاشة
|  |  |
| ------------------------------------------------------ | ----------------------------------------------------- |
| نظرة عامة | بدء النشاط |
|  |  |
| وضع Frida المحبوس | وضع Frida الكامل |
|  |  |
| متصفح الملفات | مدير التطبيقات |
|  |  |
| الطرفية | السجلات |
## ⚙️ الإعدادات
يُعد ملف `.env.sample` في الدليل الجذر نقطة انطلاق جيدة. هذه هي القائمة الكاملة لجميع متغيرات البيئة المدعومة حالياً:
| المتغير | الوصف | الافتراضي |
| ------------------------------------- | --------------------------------------------------------------------------------- | ----------- |
| `DROIDGROUND_BASE_PATH` | مسار تطبيق الويب (مفيد للاستضافة على مسارات فرعية) | - |
| `DROIDGROUND_APP_PACKAGE_NAME` | اسم حزمة التطبيق الهدف | - |
| `DROIDGROUND_ADB_HOST` | مضيف ADB | `localhost` |
| `DROIDGROUND_ADB_PORT` | منفذ ADB | `5037` |
| `DROIDGROUND_ADB_SERIAL` | الرقم التسلسلي الاختياري لجهاز ADB للاتصال به | - |
| `DROIDGROUND_DEVICE_TYPE` | `usb` أو `network` | `usb` |
| `DROIDGROUND_DEVICE_HOST` | عنوان IP لجهاز Android (`adb`) (وضع الشبكة فقط) | - |
| `DROIDGROUND_DEVICE_PORT` | منفذ جهاز Android (`adb`) (وضع الشبكة فقط) | - |
| `DROIDGROUND_INIT_SCRIPTS_FOLDER` | المجلد الذي يحتوي على `setup.sh` و `reset.sh` | `/init.d` |
| `DROIDGROUND_HOST` | عنوان الربط | `0.0.0.0` |
| `DROIDGROUND_PORT` | منفذ الربط | `4242` |
| `DROIDGROUND_RESTART_APP_DISABLED` | تعطيل إعادة تشغيل التطبيق | `false` |
| `DROIDGROUND_APP_MANAGER_DISABLED` | تعطيل مدير التطبيقات | `false` |
| `DROIDGROUND_BUG_REPORT_DISABLED` | تعطيل تقرير الأخطاء | `false` |
| `DROIDGROUND_FILE_BROWSER_DISABLED` | تعطيل متصفح الملفات | `false` |
| `DROIDGROUND_FRIDA_DISABLED` | تعطيل دعم Frida | `false` |
| `DROIDGROUND_FRIDA_TYPE` | `jail` أو `full` | `jail` |
| `DROIDGROUND_FRIDA_INJECTION` | `server` أو `gadget` | `server` |
| `DROIDGROUND_LOGCAT_DISABLED` | تعطيل logcat | `false` |
| `DROIDGROUND_REBOOT_ENABLED` | تفعيل إعادة التشغيل | `false` |
| `DROIDGROUND_SHUTDOWN_ENABLED` | تفعيل إيقاف التشغيل | `false` |
| `DROIDGROUND_START_ACTIVITY_DISABLED` | تعطيل startActivity | `false` |
| `DROIDGROUND_START_RECEIVER_DISABLED` | تعطيل البث | `false` |
| `DROIDGROUND_START_SERVICE_DISABLED` | تعطيل startService | `false` |
| `DROIDGROUND_TERMINAL_DISABLED` | تعطيل الطرفية | `false` |
| `DROIDGROUND_RESET_DISABLED` | تعطيل إعادة الضبط | `false` |
| `DROIDGROUND_SCRCPY_CONTROL_ENABLED` | تفعيل إدخال الفأرة واللمس ولوحة المفاتيح عبر شاشة الجهاز | `false` |
| `DROIDGROUND_SCRCPY_MAX_SIZE` | الحد الأقصى لبُعد الفيديو بالبكسل؛ `0` يحافظ على دقة الجهاز الكاملة | `1280` |
| `DROIDGROUND_SCRCPY_MAX_FPS` | الحد الأقصى لمعدل إطارات الفيديو؛ `0` يتركه بلا حد | `60` |
| `DROIDGROUND_SCRCPY_VIDEO_BIT_RATE` | معدل بت الفيديو بالبت في الثانية | `4000000` |
| `DROIDGROUND_EXPLOIT_APP_DURATION` | المدة (بالثواني) التي سيكون فيها تطبيق الاستغلال نشطاً | `10` |
| `DROIDGROUND_EXPLOIT_APP_MAX_SIZE` | الحد الأقصى لحجم (بالميجابايت) تطبيق الاستغلال | `50` |
| `DROIDGROUND_NUM_TEAMS` | عدد الفرق التي تلعب في وقت واحد | - |
| `DROIDGROUND_TEAM_TOKEN_<N>` | رمز الفريق رقم n. يُنشأ تلقائياً إذا كان مفقوداً | - |
| `DROIDGROUND_IP_STATIC` | عنوان IP الثابت المراد عرضه. له الأولوية على `DROIDGROUND_IP_IFACE` | - |
| `DROIDGROUND_IP_IFACE` | واجهة الشبكة لعنوان IP المعروض | - |
| `DROIDGROUND_LOGO_LINK` | تعيين رابط النقر على الشعار اختيارياً (مثل صفحة CTF الرئيسية الخاصة بك) | - |
اضبط `DROIDGROUND_SCRCPY_CONTROL_ENABLED=true` وأعد تشغيل DroidGround لجعل شاشة الجهاز تفاعلية. انقر أو المس الشاشة لتركيزها، ثم انقر أو اسحب أو مرّر، أو استخدم نقاط لمس متعددة، أو مرّر بعجلة الفأرة، أو اكتب. انقر بزر الفأرة الأيمن أو اضغط Escape للرجوع في Android. ينقل Tab و Shift+Tab التركيز خارج الشاشة. الإدخال مشترك بين كل من يشاهد الجهاز، بما في ذلك في وضع الفرق. يبقى الافتراضي شاشة للعرض فقط. يستخدم إدخال النص حقن مفاتيح Android الخاص بـ scrcpy، لذا يعتمد دعم الأحرف على تعيين لوحة مفاتيح الجهاز.
يبحث `DROIDGROUND_IP_IFACE` عن تطابق تام أولاً ثم يتراجع إلى أول واجهة _تبدأ بـ_ القيمة المقدمة، لأن Docker يسمح فقط بتحديد **بادئة** واجهة الشبكة داخل الحاوية.
يستخدم بث الشاشة افتراضياً بُعداً أقصى قدره 1280 بكسل، وحتى 60 إطاراً في الثانية، و4 ميجابت في الثانية لتقليل عمل الترميز والشبكة والمتصفح. وهذا يقايض بعض التفاصيل الدقيقة مقابل الاستجابة في عرض الجهاز المضمّن. اضبط `DROIDGROUND_SCRCPY_MAX_SIZE=0` و `DROIDGROUND_SCRCPY_VIDEO_BIT_RATE=10000000` لاستعادة إعدادات الجودة السابقة بالدقة الكاملة. بالنسبة للاتصالات أو المتصفحات الأبطأ، جرّب حجماً أقصى `1024`، و`30` إطاراً في الثانية، و`2000000` بت في الثانية. أعد تشغيل DroidGround بعد تغيير هذه الإعدادات.
يستخدم المتصفح WebCodecs عند توفره ويتراجع إلى مفكك ترميز H.264 البرمجي بخلاف ذلك. يتطلب WebCodecs سياقاً آمناً: استخدم HTTPS للنشر عن بُعد (localhost يعمل أيضاً). يستخدم HTTP العادي على IP أو اسم مضيف بعيد فك الترميز البرمجي. يتخطى المشاهدون البطيئون إلى إطار مفتاحي جديد بدلاً من تراكم تراكم فيديو. إذا لم يصل أي إطار مفتاحي خلال 1.5 ثانية، يطلب DroidGround تحديث الفيديو؛ وهذا يدعم المرمّزات مثل `OMX.google.h264.encoder` الخاص بـ ReDroid، الذي لا تكون إطارات I الدورية فيه بالضرورة إطارات IDR قابلة لفك الترميز بشكل مستقل. تُشارك طلبات التحديث بين المشاهدين وقد تحدّث الشاشة لفترة وجيزة للجميع. يحتفظ الخادم بقناة تحكم scrcpy داخلية لتحديثات الفيديو؛ يبقى إدخال الفأرة واللمس ولوحة المفاتيح والاستيقاظ التلقائي للشاشة مقيّداً بـ `DROIDGROUND_SCRCPY_CONTROL_ENABLED`. راجع [مواصفات WebCodecs](https://www.w3.org/TR/webcodecs/#videodecoder-interface) و[توثيق فيديو scrcpy](https://github.com/Genymobile/scrcpy/blob/master/doc/video.md) لإعدادات المتصفح والفيديو الأساسية.
يغيّر استخدام المتغير `DROIDGROUND_NUM_TEAMS` سلوك التطبيق قليلاً تحت الغطاء. إذا تم تعيين هذا الخيار:
1. تُفعّل ميزة خادم الاستغلال، مما يسمح لكل فريق باستخدام خادم الاستغلال الخاص به (البسيط جداً) عبر **_رمز الفريق_** الخاص به.
2. سيكون **_رمز الفريق_** **مطلوباً** لتثبيت وتشغيل تطبيقات الاستغلال. سيُربط كل تطبيق مثبّت بفريق ولن تتمكن الفرق الأخرى من تشغيله.
يتيح ذلك مشاركة نفس نسخة DroidGround مع فرق متعددة في التحديات التي يمكن فيها تسريب العلم عبر طلب شبكة. وهذا **يقلل بشكل هائل تكاليف نشر DroidGround** لمسابقات CTF.
علاوة على ذلك، إذا تم تعيين القيمة إلى `-1` فسيتم تفعيل ما يسمى بوضع **الفرق غير المحدودة**. في هذا الوضع سيكون هناك زر متاح في صفحة _نظرة عامة_ لإنشاء **_رمز فريق_** جديد. يتم تجاهل جميع متغيرات `DROIDGROUND_TEAM_TOKEN_<N>` إذا تم تفعيل هذا الوضع.
## 🧩 حالات الاستخدام
فيما يلي بعض الطرق التي يمكن بها استخدام DroidGround:
1. **نشاط مخفي**: ابحث عن نشاط غير مكشوف وشغّله لرؤية العلم (يحتوي تطبيق اللاعب على علم وهمي).
2. **RCE**: التطبيق عرضة لتنفيذ التعليمات عن بُعد والعلم مخزّن على الجهاز.
3. **أدوات Frida**: حمّل دالة بشكل زائد واستخرج العلم من الذاكرة الخاصة باستخدام سكربت.
## ⚙️ الاستخدام
يتم توفير بضعة ملفات _Docker Compose_ نموذجية في مجلد [examples](https://github.com/secforce/droidground/blob/main/examples/apps). وهي تستخدم تطبيقات من [مستودع عينات DroidGround](https://github.com/SECFORCE/droidground-samples) الذي سيتم تحسينه تدريجياً لعرض جميع الميزات الرئيسية. كما أنها نقطة انطلاق جيدة لفهم كيفية إعداد CTF الخاص بك.
عند الإقلاع يقوم _DroidGround_ بما يلي:
1. إعداد الاتصال مع `adb`
2. تشغيل `setup.sh` في المجلد المحدد بواسطة `DROIDGROUND_INIT_SCRIPTS_FOLDER` إذا كان موجوداً. يمكن استخدام هذا السكربت لتثبيت التطبيق الهدف وفعل كل ما يلزم لتهيئة CTF (مثل وضع العلم في موقع معروف)
3. (إذا كانت _Frida_ مفعّلة) تنزيل `frida-server` الصحيح بناءً على الإصدار المثبّت ومعمارية الجهاز وتشغيله
4. تشغيل التطبيق الهدف (المحدد عبر `DROIDGROUND_APP_PACKAGE_NAME`). إذا لم يكن التطبيق مثبّتاً فسيخرج _DroidGround_.
5. إعداد _REST APIs_ وخوادم _WebSocket_ وبث الشاشة
فيما يلي سكربت `setup.sh` نموذجي:
```sh
#!/usr/bin/env bash
adb shell pm uninstall com.example.app # To do some cleanup
echo "Sleep for 2 seconds before installing app"
sleep 2
echo "Installing app..."
adb install ./flag.apk # The cwd is set to the "init.d" folder, so the apk file can be accessed with the relative path
echo "Install command executed"
```
لنشر إنتاجي (في CTF حقيقي) قد ترغب في توفير عدد محدد مسبقاً من نسخ DroidGround مسبقاً أو قد ترغب في السماح للمستخدمين بإنشاء نسخ (مع قيود أو ربما ربط كل فريق/مستخدم بنسخة محددة). لهذا السبب أضفنا أيضاً [مثال spawner](https://github.com/secforce/droidground/blob/main/examples/spawner) بسيط.
بدلاً من ذلك، كما ذُكر سابقاً، يمكنك إنشاء تحدٍّ يمكن فيه تسريب العلم عبر طلب شبكة والاستفادة من متغير البيئة `DROIDGROUND_NUM_TEAMS` لتجنب إنشاء نسخ متعددة (والتي قد تكون مكلفة). يوفر مجلد [net-multi-step](https://github.com/secforce/droidground/blob/main/examples/apps/net-multi-step) مثالاً جيداً على كيفية تقديم هذا النوع من التحديات.
## 💡 نصائح
فيما يلي بعض الاقتراحات لإعداد CTF الخاص بـ Android:
- كن حذراً عند تفعيل **وضع Frida الكامل**، سيكون للاعب تحكم كامل في الجهاز (لهذا السبب أنشأنا **وضع Frida المحبوس** كما هو مفصل في [مكتبة Frida](https://github.com/secforce/droidground/blob/main/library)).
- كن حذراً عند تفعيل **الطرفية**، سيكون للاعب تحكم كامل في الجهاز.
- كن حذراً عند تفعيل ميزة **إيقاف التشغيل**.
- إذا كنت تخطط لجعل العلم مرئياً مباشرة في واجهة المستخدم فقد ترغب في إيجاد طريقة لإنشاء نسخ مختلفة (واحدة لكل فريق/لاعب)
أثناء اختبار الإعداد قبل الانتقال إلى الإنتاج قد يكون من المفيد الحصول على **سطح الهجوم** للتطبيق الهدف. هذا شيء لا ينبغي للاعبين رؤيته لأنه جزء من مهمتهم اكتشاف سطح الهجوم وتحليله!
لذلك، يتم توفير نقطة نهاية `GET` يمكن الوصول إليها على `/attackSurface` ومحمية برمز (يجب استخدامه كقيمة لترويسة `Authorization`) يتم إنشاؤه عشوائياً أثناء الإقلاع وطباعته في السجلات (وبالتالي يمكن الوصول إليه فقط من قبل مسؤولي النظام).
إذا كنت ترغب في استخدام سكربتات Frida الخاصة بك في وضع الحبس، فأنت تحتاج فقط إلى ربط المجلد الذي يحتوي عليها بشكل bind-mount داخل حاوية Docker:
```yaml
volumes:
- <Frida library folder>:/droidground/library
```
مطلوب ملف `library.json` (مثل الموجود في [library](https://github.com/secforce/droidground/blob/main/library/library.json)) لإرشاد التطبيق إلى قائمة السكربتات المتاحة.
## 🛠 التطوير
لا ينبغي أن يكون تشغيله صعباً للغاية، لكن قبل البدء يجب أن تكون الأدوات التالية مثبّتة لديك:
- `frida` (فقط إذا فعّلت _Frida_)
- `node` (إنه تطبيق Node، يجب أن يكون لديك!)
- `adb` (حسناً، نحن نعتمد عليه للتحدث مع الجهاز)
- _JDK_ (تحتاجه لبناء التطبيق المرافق)
بعد ذلك يمكنك ببساطة تشغيل ما يلي:
```sh
git clone https://github.com/SECFORCE/droidground.git
cd droidground
# Install without running scripts
npm install --ignore-scripts
# Rebuild frida to get the bindings
npm rebuild frida
# Build companion app
npm run companion
# Get scrcpy
npm run scrcpy
```
بعد ذلك تحتاج فقط إلى تعيين متغيرات **env** ثم تشغيل `npm run dev` وستكون جاهزاً للانطلاق. وضع تطوير سعيد!
## 🤝 المساهمة
طلبات السحب مرحّب بها! يرجى فتح issue أولاً لمناقشة التغييرات الكبيرة. الأفكار الخاصة بسير عمل CTF الجديدة أو أنواع التحديات محل تقدير خاص.
## 📚 الشكر والتقدير
تم تطويره بواسطة [Angelo Delicato](https://github.com/thelicato) [@SECFORCE](https://www.secforce.com).
يعتمد قسم _server_ بشكل كبير على العمل الرائع الذي قام به [@yume-chan](https://github.com/yume-chan/ya-webadb)، وربما لم يكن هذا التطبيق موجوداً لولا عمله الرائع.
يعتمد تطبيق _companion_ بشكل كبير على [aya server](https://github.com/liriliri/aya/tree/master/server) الذي يعمل بنفس طريقة [scrcpy server](https://github.com/Genymobile/scrcpy). يمكن العثور على مزيد من التفاصيل في [README](https://github.com/secforce/droidground/blob/main/companion/README.md) المحدد.
## 🪪 الترخيص
يُصدر _DroidGround_ بموجب [رخصة GPL-3.0](https://github.com/SECFORCE/droidground/blob/main/LICENSE)