
Un terrain de jeu flexible pour les défis CTF Android.
<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">Site web</a> |
<a href="https://droidground.com/demo" target="_blank">Démo</a>
</p>
Dans les **challenges CTF** traditionnels, il est courant de cacher les flags dans des fichiers sur un système, obligeant les attaquants à exploiter des vulnérabilités pour les récupérer. Cependant, dans le monde Android, cette approche ne fonctionne pas bien. Les fichiers APK sont facilement téléchargeables et réversibles, donc **placer un flag sur l'appareil le rend généralement trivial** à extraire par analyse statique ou par des astuces d'émulateur. Cela limite sévèrement la capacité à créer des challenges réalistes centrés sur l'exécution.
_DroidGround_ est conçu pour résoudre ce problème.
C'est une plateforme sur mesure pour héberger des challenges de hacking mobile Android dans un environnement **contrôlé** et **réaliste**, où **les attaquants sont suffisamment contraints** pour devoir résoudre les challenges de la manière prévue.
Point important, les participants peuvent être **enfermés dans l'environnement de l'application**. La modularité de l'outil permet de définir si l'utilisateur peut ou non lancer un shell, lire des fichiers arbitraires ou installer des outils en sideload. Tout peut être configuré de sorte que le seul moyen de récupérer le flag soit de comprendre et d'exploiter l'application elle-même.
## 📋 Table des matières
- [🧭 Aperçu](#-aperçu)
- [✨ Fonctionnalités](#-fonctionnalités)
- [📸 Captures d'écran](#-captures-décran)
- [⚙️ Configuration](#️-configuration)
- [🧩 Cas d'usage](#-cas-dusage)
- [⚙️ Utilisation](#️-utilisation)
- [💡 Astuces](#-astuces)
- [🛠 Développement](#-développement)
- [🤝 Contribution](#-contribution)
- [📚 Crédits](#-crédits)
- [🪪 Licence](#-licence)
## 🧭 Aperçu
_DroidGround_ permet une grande variété de challenges _Android_ autrement difficiles à mettre en œuvre dans les configurations CTF traditionnelles. Par exemple, dans un challenge d'exécution de code à distance (RCE), les joueurs peuvent recevoir un APK pour une analyse locale. Après avoir découvert une vulnérabilité, ils peuvent développer un script Frida et l'exécuter via DroidGround sur l'appareil cible réel pour extraire le flag du stockage interne. D'autres types de challenges peuvent impliquer des activités cachées, des intents de diffusion personnalisés, l'exploitation de services ou l'analyse dynamique à l'aide d'outils préchargés.
Avec le streaming de l'appareil en temps réel, un contrôle fin des fonctionnalités, l'intégration de Frida et des scripts de configuration et de réinitialisation personnalisables, DroidGround permet aux organisateurs de CTF de créer des challenges Android sécurisés, flexibles et réalistes qui vont bien au-delà de ce qui est habituellement possible.
## ✨ Fonctionnalités
DroidGround fournit un ensemble riche de fonctionnalités contrôlées par le serveur.
- **Écran de l'appareil en temps réel** (via `scrcpy`), avec contrôle optionnel à la souris, au toucher et au clavier
- **Réinitialisation de l'état du challenge**
- **Redémarrer l'application / Démarrer une activité / Démarrer un service**
- **Envoyer un intent de diffusion**
- **Éteindre / Redémarrer l'appareil**
- **Télécharger le rapport de bug (bugreportz)**
- **Scripting Frida**
- Exécution depuis une bibliothèque préchargée (mode restreint)
- Exécution de scripts arbitraires (mode complet)
- **Navigateur de fichiers**
- **Accès au terminal**
- **Gestion des APK**
- **Visionneuse Logcat**
- **Serveur d'exploit** (si le mode équipe est activé)
Presque toutes les fonctionnalités sont **modulaires** et définies via des variables d'environnement, garantissant un contrôle précis du périmètre du challenge.
## 📸 Captures d'écran
|  |  |
| ------------------------------------------------------ | ----------------------------------------------------- |
| Vue d'ensemble | Démarrer une activité |
|  |  |
| Mode Frida Jailed | Mode Frida complet |
|  |  |
| Navigateur de fichiers | Gestionnaire d'applications |
|  |  |
| Terminal | Journaux |
## ⚙️ Configuration
Le fichier `.env.sample` situé dans le répertoire racine est un bon point de départ. Voici la liste complète de toutes les variables d'environnement actuellement prises en charge :
| Variable | Description | Default |
| ------------------------------------- | --------------------------------------------------------------------------------- | ----------- |
| `DROIDGROUND_BASE_PATH` | Chemin de l'application web (utile pour l'hébergement sur des sous-chemins) | - |
| `DROIDGROUND_APP_PACKAGE_NAME` | Nom du package de l'application cible | - |
| `DROIDGROUND_ADB_HOST` | Hôte ADB | `localhost` |
| `DROIDGROUND_ADB_PORT` | Port ADB | `5037` |
| `DROIDGROUND_ADB_SERIAL` | Numéro de série ADB facultatif de l'appareil auquel se connecter | - |
| `DROIDGROUND_DEVICE_TYPE` | `usb` ou `network` | `usb` |
| `DROIDGROUND_DEVICE_HOST` | IP de l'appareil Android (`adb`) (mode réseau uniquement) | - |
| `DROIDGROUND_DEVICE_PORT` | port de l'appareil Android (`adb`) (mode réseau uniquement) | - |
| `DROIDGROUND_INIT_SCRIPTS_FOLDER` | Dossier contenant `setup.sh` et `reset.sh` | `/init.d` |
| `DROIDGROUND_HOST` | Adresse de liaison | `0.0.0.0` |
| `DROIDGROUND_PORT` | Port de liaison | `4242` |
| `DROIDGROUND_RESTART_APP_DISABLED` | Désactiver le redémarrage de l'application | `false` |
| `DROIDGROUND_APP_MANAGER_DISABLED` | Désactiver le gestionnaire d'applications | `false` |
| `DROIDGROUND_BUG_REPORT_DISABLED` | Désactiver le rapport de bug | `false` |
| `DROIDGROUND_FILE_BROWSER_DISABLED` | Désactiver le navigateur de fichiers | `false` |
| `DROIDGROUND_FRIDA_DISABLED` | Désactiver la prise en charge de Frida | `false` |
| `DROIDGROUND_FRIDA_TYPE` | `jail` ou `full` | `jail` |
| `DROIDGROUND_FRIDA_INJECTION` | `server` ou `gadget` | `server` |
| `DROIDGROUND_LOGCAT_DISABLED` | Désactiver logcat | `false` |
| `DROIDGROUND_REBOOT_ENABLED` | Activer le redémarrage | `false` |
| `DROIDGROUND_SHUTDOWN_ENABLED` | Activer l'arrêt | `false` |
| `DROIDGROUND_START_ACTIVITY_DISABLED` | Désactiver startActivity | `false` |
| `DROIDGROUND_START_RECEIVER_DISABLED` | Désactiver la diffusion | `false` |
| `DROIDGROUND_START_SERVICE_DISABLED` | Désactiver startService | `false` |
| `DROIDGROUND_TERMINAL_DISABLED` | Désactiver le terminal | `false` |
| `DROIDGROUND_RESET_DISABLED` | Désactiver la réinitialisation | `false` |
| `DROIDGROUND_SCRCPY_CONTROL_ENABLED` | Activer la saisie souris, tactile et clavier via l'écran de l'appareil | `false` |
| `DROIDGROUND_SCRCPY_MAX_SIZE` | Dimension vidéo maximale en pixels ; `0` conserve la résolution complète de l'appareil | `1280` |
| `DROIDGROUND_SCRCPY_MAX_FPS` | Fréquence d'images vidéo maximale ; `0` la laisse sans limite | `60` |
| `DROIDGROUND_SCRCPY_VIDEO_BIT_RATE` | Débit binaire vidéo en bits par seconde | `4000000` |
| `DROIDGROUND_EXPLOIT_APP_DURATION` | La durée (en secondes) pendant laquelle l'application d'exploit sera active | `10` |
| `DROIDGROUND_EXPLOIT_APP_MAX_SIZE` | La taille maximale (en Mo) de l'application d'exploit | `50` |
| `DROIDGROUND_NUM_TEAMS` | Le nombre d'équipes jouant simultanément | - |
| `DROIDGROUND_TEAM_TOKEN_<N>` | Le jeton de la n-ième équipe. Généré automatiquement s'il est absent | - |
| `DROIDGROUND_IP_STATIC` | L'adresse IP statique à afficher. Elle a la priorité sur `DROIDGROUND_IP_IFACE` | - |
| `DROIDGROUND_IP_IFACE` | L'interface réseau pour l'adresse IP affichée | - |
| `DROIDGROUND_LOGO_LINK` | Définit facultativement le lien de clic du logo (par ex., votre page principale de CTF) | - |
Définissez `DROIDGROUND_SCRCPY_CONTROL_ENABLED=true` et redémarrez DroidGround pour rendre l'écran de l'appareil interactif. Cliquez ou touchez l'écran pour le focaliser, puis cliquez, faites glisser, balayez, utilisez plusieurs points de contact, faites défiler avec la molette de la souris ou saisissez du texte. Un clic droit ou la touche Échap déclenche le retour Android. Tab et Maj+Tab déplacent le focus hors de l'écran. L'entrée est partagée par toutes les personnes qui consultent l'appareil ; pendant une exécution d'exploit d'équipe, seuls les spectateurs authentifiés en tant que cette équipe peuvent le voir ou le contrôler. Par défaut, l'écran reste en lecture seule. La saisie de texte utilise l'injection de touches Android de scrcpy, la prise en charge des caractères dépend donc du mappage clavier de l'appareil.
La variable `DROIDGROUND_IP_IFACE` recherche d'abord une correspondance exacte et, à défaut, se rabat sur la première interface qui _commence par_ la valeur fournie, car Docker ne permet de spécifier que le **préfixe** de l'interface réseau au sein du conteneur.
Le streaming d'écran utilise par défaut une dimension maximale de 1280 pixels, jusqu'à 60 fps et 4 Mbps afin de réduire la charge d'encodage, de réseau et du navigateur. Cela sacrifie un peu de finesse au profit de la réactivité dans la vue d'appareil intégrée. Définissez `DROIDGROUND_SCRCPY_MAX_SIZE=0` et `DROIDGROUND_SCRCPY_VIDEO_BIT_RATE=10000000` pour restaurer les paramètres de qualité en pleine résolution précédents. Pour les connexions ou navigateurs plus lents, essayez une taille maximale de `1024`, `30` fps et `2000000` bits par seconde. Redémarrez DroidGround après avoir modifié ces paramètres.
Le navigateur utilise WebCodecs lorsqu'il est disponible et se rabat sinon sur le décodeur H.264 logiciel. WebCodecs nécessite un contexte sécurisé : utilisez HTTPS pour les déploiements distants (localhost fonctionne également). Le HTTP simple sur une IP ou un nom d'hôte distant utilise le décodage logiciel. Les spectateurs lents sautent vers une nouvelle image clé au lieu d'accumuler un retard vidéo. Si aucune image clé n'arrive dans les 1,5 secondes, DroidGround demande un rafraîchissement vidéo ; cela prend en charge des encodeurs tels que `OMX.google.h264.encoder` de ReDroid, dont les I-frames périodiques ne sont pas nécessairement des trames IDR décodables indépendamment. Les demandes de rafraîchissement sont partagées entre les spectateurs et peuvent brièvement rafraîchir l'écran pour tout le monde. Le serveur conserve un canal de contrôle scrcpy interne pour les rafraîchissements vidéo ; la souris, le tactile, la saisie au clavier et le réveil automatique de l'écran restent conditionnés par `DROIDGROUND_SCRCPY_CONTROL_ENABLED`. Consultez la [spécification WebCodecs](https://www.w3.org/TR/webcodecs/#videodecoder-interface) et la [documentation vidéo de scrcpy](https://github.com/Genymobile/scrcpy/blob/master/doc/video.md) pour les paramètres sous-jacents du navigateur et de la vidéo.
L'utilisation de la variable `DROIDGROUND_NUM_TEAMS` modifie légèrement le comportement de l'application en interne. Si cette option est définie :
1. La fonctionnalité de serveur d'exploit est activée, permettant à chaque équipe d'utiliser son propre serveur d'exploit (très simple) via son **_jeton d'équipe_**.
2. Le jeton d'équipe sera **requis** pour installer et exécuter des applications d'exploit. Chaque application installée sera liée à une équipe et les autres équipes ne pourront pas l'exécuter.
3. Pendant l'exécution de l'application d'exploit d'une équipe, les autres équipes et les spectateurs sans jeton voient un écran noir expliquant qu'un exploit d'une autre équipe est en cours. Le serveur retient la vidéo et rejette leur saisie sur l'appareil. L'affichage partagé reprend après le redémarrage de l'application cible. Saisissez votre jeton dans **Team token for display** sous l'appareil pour regarder les exécutions de votre équipe ; lancer un exploit depuis l'interface authentifie également automatiquement l'affichage de ce navigateur. Les jetons sont envoyés via le WebSocket plutôt que dans son URL et sont conservés en mémoire pour la page courante. Cela s'applique également en mode Unlimited Teams. Sans le mode équipe, l'affichage reste partagé.
Cela permet de partager la même instance DroidGround avec plusieurs équipes dans des challenges où le flag peut être exfiltré via une requête réseau. Cela **réduit massivement les coûts de déploiement de DroidGround** pour les compétitions CTF.
De plus, si la valeur est définie à `-1`, cela active le mode dit **Unlimited Teams**. Dans ce mode, un bouton permettant de générer un nouveau **_jeton d'équipe_** sera disponible dans la page _Overview_. Toutes les variables `DROIDGROUND_TEAM_TOKEN_<N>` sont ignorées si ce mode est activé.
## 🧩 Cas d'usage
Voici quelques façons d'utiliser DroidGround :
1. **Activité cachée** : Trouvez et lancez une activité non exposée pour voir le flag (l'application du joueur contient un faux flag).
2. **RCE** : L'application est vulnérable à une RCE et le flag est stocké sur l'appareil.
3. **Instrumentation Frida** : Surchargez une méthode et extrayez le flag de la mémoire privée à l'aide d'un script.
## ⚙️ Utilisation
Quelques fichiers _Docker Compose_ d'exemple sont fournis dans le dossier [examples](https://github.com/secforce/droidground/blob/main/examples/apps). Ils utilisent des applications du [dépôt d'exemples DroidGround](https://github.com/SECFORCE/droidground-samples) qui seront progressivement enrichies pour illustrer toutes les fonctionnalités clés. Ils constituent également un bon point de départ pour comprendre comment configurer votre propre CTF.
Au démarrage, _DroidGround_ effectue les opérations suivantes :
1. Établir la connexion avec `adb`
2. Exécuter le `setup.sh` dans le dossier spécifié par `DROIDGROUND_INIT_SCRIPTS_FOLDER` s'il est présent. Ce script peut être utilisé pour installer l'application cible et faire tout ce qui est nécessaire pour initialiser le CTF (par exemple, placer le flag dans un emplacement connu)
3. (si _Frida_ est activé) Télécharger le `frida-server` approprié en fonction de la version installée et de l'architecture de l'appareil, puis le démarrer
4. Lancer l'application cible (celle spécifiée via `DROIDGROUND_APP_PACKAGE_NAME`). Si l'application n'est pas installée, _DroidGround_ se fermera.
5. Configurer les _REST APIs_, les serveurs _WebSocket_ et la diffusion de l'affichage
Voici un exemple de script `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"
```
Pour un déploiement en production (dans un vrai CTF), vous voudrez peut-être provisionner à l'avance un nombre prédéfini d'instances DroidGround, ou autoriser les utilisateurs à créer des instances (avec une limitation, ou éventuellement associer chaque équipe/utilisateur à une instance spécifique). Pour cette raison, nous avons également ajouté un simple [exemple de spawner](https://github.com/secforce/droidground/blob/main/examples/spawner).
Alternativement, comme mentionné précédemment, vous pouvez créer un challenge où le flag peut être exfiltré via une requête réseau et exploiter la variable d'environnement `DROIDGROUND_NUM_TEAMS` pour éviter de créer plusieurs instances (ce qui pourrait être coûteux). Le dossier [net-multi-step](https://github.com/secforce/droidground/blob/main/examples/apps/net-multi-step) fournit un bon exemple de la façon de proposer ce type de challenges.
## 💡 Astuces
Voici quelques suggestions pour configurer votre CTF Android :
- Faites attention lorsque vous activez le **Frida Full Mode**, le joueur aura le contrôle total de l'appareil (c'est pourquoi nous avons créé le **Frida Jail Mode** comme détaillé dans [Frida Library](https://github.com/secforce/droidground/blob/main/library)).
- Faites attention lorsque vous activez le **Terminal**, le joueur aura le contrôle total de l'appareil.
- Faites attention lorsque vous activez la fonctionnalité **Shutdown**.
- Si vous prévoyez de rendre le flag directement visible dans l'interface utilisateur, vous voudrez peut-être trouver un moyen de créer différentes instances (une pour chaque équipe/joueur)
Lors des tests de la configuration avant de passer en production, il pourrait être utile d'obtenir la **surface d'attaque** de l'application cible. C'est quelque chose que les joueurs ne devraient pas voir, car c'est leur travail de découvrir et d'analyser la surface d'attaque !
Par conséquent, un endpoint `GET` accessible à l'adresse `/attackSurface` est fourni et protégé par un token (qui doit être utilisé comme valeur de l'en-tête `Authorization`) généré aléatoirement au démarrage et affiché dans les logs (donc accessible uniquement par les administrateurs système).
Si vous souhaitez utiliser vos propres scripts Frida en mode jail, il vous suffit de monter en bind le dossier qui les contient dans le conteneur Docker :
```yaml
volumes:
- <Frida library folder>:/droidground/library
```
Un fichier `library.json` (comme celui présent dans le [library](https://github.com/secforce/droidground/blob/main/library/library.json)) est requis pour indiquer à l'application la liste des scripts disponibles.
## 🛠 Développement
Le mettre en place et le faire fonctionner ne devrait pas être trop difficile, mais avant de commencer, vous devez avoir installé les outils suivants :
- `frida` (uniquement si vous activez _Frida_)
- `node` (c'est une application Node, vous devez l'avoir !)
- `adb` (eh bien, nous comptons sur lui pour communiquer avec l'appareil)
- _JDK_ (vous en avez besoin pour compiler l'application compagnon)
Après cela, vous pouvez simplement exécuter ce qui suit :
```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
```
Ensuite, il vous suffit de définir les variables d'**env** puis d'exécuter `npm run dev` et vous serez prêt. Bon mode dev !
## 🤝 Contribuer
Les pull requests sont les bienvenues ! Veuillez d'abord ouvrir une issue pour discuter des changements majeurs. Les idées de nouveaux workflows CTF ou types de challenges sont particulièrement appréciées.
## 📚 Crédits
Développé par [Angelo Delicato](https://github.com/thelicato) [@SECFORCE](https://www.secforce.com).
La section _server_ repose fortement sur l'excellent travail réalisé par [@yume-chan](https://github.com/yume-chan/ya-webadb) ; cette application n'existerait probablement pas sans son travail remarquable.
L'application _companion_ est largement basée sur le [aya server](https://github.com/liriliri/aya/tree/master/server) qui fonctionne de la même manière que le [scrcpy server](https://github.com/Genymobile/scrcpy). Plus de détails sont disponibles dans le [README](https://github.com/secforce/droidground/blob/main/companion/README.md) spécifique.
## 🪪 Licence
_DroidGround_ est publié sous la [GPL-3.0 LICENSE](https://github.com/SECFORCE/droidground/blob/main/LICENSE)