secforce/droidgroundUn campo de pruebas flexible para retos CTF de 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">Website</a> |
<a href="https://droidground.com/demo" target="_blank">Demo</a>
</p>
En los **desafíos CTF** tradicionales, es común ocultar flags en archivos dentro de un sistema, lo que obliga a los atacantes a explotar vulnerabilidades para recuperarlas. Sin embargo, en el mundo de Android, este enfoque no funciona bien. Los archivos APK son fácilmente descargables y reversibles, por lo que **colocar una flag en el dispositivo normalmente hace que sea trivial** extraerla mediante análisis estático o trucos de emulador. Esto limita severamente la capacidad de crear desafíos realistas centrados en el runtime.
_DroidGround_ está diseñado para resolver este problema.
Es una plataforma construida a medida para alojar desafíos de hacking móvil en Android en un entorno **controlado** y **realista**, donde **los atacantes están limitados lo justo** para requerir que resuelvan los desafíos de la manera prevista.
Es importante destacar que los participantes pueden estar **encerrados dentro del entorno de la app**. La modularidad de la herramienta permite establecer si el usuario puede o no abrir una shell, leer archivos arbitrarios o instalar herramientas de forma lateral. Todo puede configurarse para que la única forma de recuperar la flag sea comprendiendo y explotando la propia app.
## 📋 Tabla de Contenidos
- [🧭 Descripción General](#-overview)
- [✨ Características](#-features)
- [📸 Capturas de Pantalla](#-screenshots)
- [⚙️ Configuración](#️-configuration)
- [🧩 Casos de Uso](#-use-cases)
- [⚙️ Uso](#️-usage)
- [💡 Consejos](#-tips)
- [🛠 Desarrollo](#-development)
- [🤝 Contribuir](#-contributing)
- [📚 Créditos](#-credits)
- [🪪 Licencia](#-license)
## 🧭 Descripción General
_DroidGround_ permite una amplia variedad de desafíos de _Android_ que de otro modo son difíciles de implementar en configuraciones CTF tradicionales. Por ejemplo, en un desafío de ejecución remota de código (RCE), los jugadores podrían recibir un APK para análisis local. Después de descubrir una vulnerabilidad, pueden desarrollar un script de Frida y ejecutarlo a través de DroidGround en el dispositivo objetivo real para extraer la flag del almacenamiento interno. Otros tipos de desafíos pueden involucrar actividades ocultas, intents de broadcast personalizados, explotación de servicios o análisis dinámico usando herramientas precargadas.
Con streaming del dispositivo en tiempo real, control detallado sobre las características, integración con Frida y scripts de configuración y reinicio personalizables, DroidGround permite a los organizadores de CTF construir desafíos de Android seguros, flexibles y realistas que van mucho más allá de lo que normalmente es posible.
## ✨ Características
DroidGround proporciona un amplio conjunto de características controladas por el servidor.
- **Pantalla del Dispositivo en Tiempo Real** (vía `scrcpy`), con control opcional de ratón, táctil y teclado
- **Reiniciar el Estado del Desafío**
- **Reiniciar App / Iniciar Actividad / Iniciar Servicio**
- **Enviar Intent de Broadcast**
- **Apagar / Reiniciar Dispositivo**
- **Descargar Bugreport (bugreportz)**
- **Scripting con Frida**
- Ejecutar desde biblioteca precargada (modo jail)
- Ejecutar scripts arbitrarios (modo full)
- **Explorador de Archivos**
- **Acceso a Terminal**
- **Gestión de APK**
- **Visor de Logcat**
- **Servidor de Exploits** (si el modo equipo está habilitado)
Casi todas las características son **modulares** y se definen mediante variables de entorno, lo que garantiza un control preciso sobre el alcance del desafío.
## 📸 Capturas de Pantalla
|  |  |
| ------------------------------------------------------ | ----------------------------------------------------- |
| Overview | Start Activity |
|  |  |
| Frida Jailed Mode | Frida Full Mode |
|  |  |
| File Browser | App Manager |
|  |  |
| Terminal | Logs |
## ⚙️ Configuración
El archivo `.env.sample` en el directorio raíz es un buen punto de partida. Esta es la lista completa de todas las variables de entorno soportadas actualmente:
| Variable | Descripción | Por Defecto |
| ------------------------------------- | --------------------------------------------------------------------------------- | ----------- |
| `DROIDGROUND_BASE_PATH` | Ruta de la webapp (útil para alojar en subrutas) | - |
| `DROIDGROUND_APP_PACKAGE_NAME` | Nombre del paquete de la app objetivo | - |
| `DROIDGROUND_ADB_HOST` | Host de ADB | `localhost` |
| `DROIDGROUND_ADB_PORT` | Puerto de ADB | `5037` |
| `DROIDGROUND_ADB_SERIAL` | Número de serie opcional del dispositivo ADB al que conectarse | - |
| `DROIDGROUND_DEVICE_TYPE` | `usb` o `network` | `usb` |
| `DROIDGROUND_DEVICE_HOST` | IP del dispositivo Android (`adb`) (solo modo network) | - |
| `DROIDGROUND_DEVICE_PORT` | Puerto del dispositivo Android (`adb`) (solo modo network) | - |
| `DROIDGROUND_INIT_SCRIPTS_FOLDER` | Carpeta que contiene `setup.sh` y `reset.sh` | `/init.d` |
| `DROIDGROUND_HOST` | Dirección de enlace | `0.0.0.0` |
| `DROIDGROUND_PORT` | Puerto de enlace | `4242` |
| `DROIDGROUND_RESTART_APP_DISABLED` | Deshabilitar reinicio de app | `false` |
| `DROIDGROUND_APP_MANAGER_DISABLED` | Deshabilitar gestor de apps | `false` |
| `DROIDGROUND_BUG_REPORT_DISABLED` | Deshabilitar bugreport | `false` |
| `DROIDGROUND_FILE_BROWSER_DISABLED` | Deshabilitar explorador de archivos | `false` |
| `DROIDGROUND_FRIDA_DISABLED` | Deshabilitar soporte de Frida | `false` |
| `DROIDGROUND_FRIDA_TYPE` | `jail` o `full` | `jail` |
| `DROIDGROUND_FRIDA_INJECTION` | `server` o `gadget` | `server` |
| `DROIDGROUND_LOGCAT_DISABLED` | Deshabilitar logcat | `false` |
| `DROIDGROUND_REBOOT_ENABLED` | Habilitar reinicio | `false` |
| `DROIDGROUND_SHUTDOWN_ENABLED` | Habilitar apagado | `false` |
| `DROIDGROUND_START_ACTIVITY_DISABLED` | Deshabilitar startActivity | `false` |
| `DROIDGROUND_START_RECEIVER_DISABLED` | Deshabilitar broadcast | `false` |
| `DROIDGROUND_START_SERVICE_DISABLED` | Deshabilitar startService | `false` |
| `DROIDGROUND_TERMINAL_DISABLED` | Deshabilitar terminal | `false` |
| `DROIDGROUND_RESET_DISABLED` | Deshabilitar reinicio | `false` |
| `DROIDGROUND_SCRCPY_CONTROL_ENABLED` | Habilitar entrada de ratón, táctil y teclado a través de la pantalla del dispositivo | `false` |
| `DROIDGROUND_SCRCPY_MAX_SIZE` | Dimensión máxima de vídeo en píxeles; `0` mantiene la resolución completa del dispositivo | `1280` |
| `DROIDGROUND_SCRCPY_MAX_FPS` | Tasa de fotogramas máxima de vídeo; `0` la deja sin límite | `60` |
| `DROIDGROUND_SCRCPY_VIDEO_BIT_RATE` | Bitrate de vídeo en bits por segundo | `4000000` |
| `DROIDGROUND_EXPLOIT_APP_DURATION` | El tiempo (en segundos) que la app de exploit estará activa | `10` |
| `DROIDGROUND_EXPLOIT_APP_MAX_SIZE` | El tamaño máximo (en MB) de la app de exploit | `50` |
| `DROIDGROUND_NUM_TEAMS` | El número de equipos jugando simultáneamente | - |
| `DROIDGROUND_TEAM_TOKEN_<N>` | El token para el n-ésimo equipo. Se genera automáticamente si falta | - |
| `DROIDGROUND_IP_STATIC` | La dirección IP estática a mostrar. Tiene prioridad sobre `DROIDGROUND_IP_IFACE` | - |
| `DROIDGROUND_IP_IFACE` | La interfaz de red para la dirección IP mostrada | - |
| `DROIDGROUND_LOGO_LINK` | Establecer opcionalmente el enlace de clic del logo (p. ej., tu página principal del CTF) | - |
Establece `DROIDGROUND_SCRCPY_CONTROL_ENABLED=true` y reinicia DroidGround para hacer que la pantalla del dispositivo sea interactiva. Haz clic o toca la pantalla para enfocarla, luego haz clic, arrastra, desliza, usa múltiples puntos táctiles, desplázate con la rueda del ratón o escribe. Haz clic derecho o pulsa Escape para el botón Atrás de Android. Tab y Shift+Tab mueven el foco fuera de la pantalla. La entrada es compartida por todos los que ven el dispositivo, incluso en modo equipo. El valor predeterminado sigue siendo una pantalla de solo visualización. La entrada de texto utiliza la inyección de teclas de Android de scrcpy, por lo que el soporte de caracteres depende de la asignación de teclado del dispositivo.
`DROIDGROUND_IP_IFACE` busca primero una coincidencia exacta y recurre a la primera interfaz que _comience con_ el valor proporcionado, ya que Docker solo permite especificar el **prefijo** de la interfaz de red dentro del contenedor.
El streaming de pantalla por defecto tiene una dimensión máxima de 1280 píxeles, hasta 60 fps y 4 Mbps para reducir el trabajo de codificación, red y navegador. Esto sacrifica algo de detalle fino por capacidad de respuesta en la vista del dispositivo integrada. Establece `DROIDGROUND_SCRCPY_MAX_SIZE=0` y `DROIDGROUND_SCRCPY_VIDEO_BIT_RATE=10000000` para restaurar la configuración de calidad de resolución completa anterior. Para conexiones o navegadores más lentos, prueba un tamaño máximo de `1024`, `30` fps y `2000000` bits por segundo. Reinicia DroidGround después de cambiar estas configuraciones.
El navegador usa WebCodecs cuando está disponible y recurre al decodificador H.264 por software en caso contrario. WebCodecs requiere un contexto seguro: usa HTTPS para despliegues remotos (localhost también funciona). HTTP simple en una IP o nombre de host remoto usa decodificación por software. Los visores lentos saltan a un fotograma clave nuevo en lugar de acumular un retraso de vídeo. Si no llega ningún fotograma clave en 1,5 segundos, DroidGround solicita una actualización de vídeo; esto soporta codificadores como `OMX.google.h264.encoder` de ReDroid, cuyos I-frames periódicos no son necesariamente fotogramas IDR decodificables de forma independiente. Las solicitudes de actualización se comparten entre visores y pueden refrescar brevemente la pantalla para todos. El servidor mantiene un canal de control interno de scrcpy para las actualizaciones de vídeo; la entrada de ratón, táctil, teclado y el despertar automático de la pantalla siguen condicionados por `DROIDGROUND_SCRCPY_CONTROL_ENABLED`. Consulta la [especificación de WebCodecs](https://www.w3.org/TR/webcodecs/#videodecoder-interface) y la [documentación de vídeo de scrcpy](https://github.com/Genymobile/scrcpy/blob/master/doc/video.md) para conocer la configuración subyacente del navegador y del vídeo.
El uso de la variable `DROIDGROUND_NUM_TEAMS` cambia ligeramente el comportamiento de la aplicación internamente. Si esta opción está establecida:
1. La característica del servidor de exploits se habilita, permitiendo que cada equipo pueda usar su propio (muy simple) servidor de exploits a través de su **_team token_**.
2. El team token será **requerido** para instalar y ejecutar apps de exploit. Cada app instalada estará vinculada a un equipo y otros equipos no podrán ejecutarla.
Esto permite compartir la misma instancia de DroidGround con múltiples equipos en desafíos donde la flag puede ser exfiltrada mediante una solicitud de red. Esto **reduce masivamente los costes de despliegue de DroidGround** para competiciones CTF.
Además, si el valor se establece en `-1`, habilitará el llamado modo **Unlimited Teams**. En este modo, un botón para generar un nuevo **_team token_** estará disponible en la página _Overview_. Todas las variables `DROIDGROUND_TEAM_TOKEN_<N>` se ignoran si este modo está habilitado.
## 🧩 Casos de Uso
Aquí hay algunas formas en que se puede usar DroidGround:
1. **Actividad Oculta**: Encontrar y lanzar una actividad no expuesta para ver la flag (la app del jugador contiene una flag ficticia).
2. **RCE**: La app es vulnerable a RCE y la flag está almacenada en el dispositivo.
3. **Instrumentación con Frida**: Sobrecargar un método y extraer la flag de la memoria privada usando un script.
## ⚙️ Uso
Se proporcionan un par de archivos _Docker Compose_ de ejemplo en la carpeta [examples](https://github.com/secforce/droidground/blob/main/examples/apps). Usan apps del [repositorio de ejemplos de DroidGround](https://github.com/SECFORCE/droidground-samples), que se mejorará progresivamente para mostrar todas las características clave. También son un buen punto de partida para entender cómo configurar tu propio CTF.
Al arrancar, _DroidGround_ hace lo siguiente:
1. Establece la conexión con `adb`
2. Ejecuta el `setup.sh` en la carpeta especificada por `DROIDGROUND_INIT_SCRIPTS_FOLDER` si está presente. Este script puede usarse para instalar la app objetivo y hacer todo lo demás que sea necesario para inicializar el CTF (p. ej., colocar la flag en una ubicación conocida)
3. (si _Frida_ está habilitado) Descarga el `frida-server` correcto según la versión instalada y la arquitectura del dispositivo y lo inicia
4. Ejecuta la app objetivo (la especificada mediante `DROIDGROUND_APP_PACKAGE_NAME`). Si la app no está instalada, _DroidGround_ saldrá.
5. Configura las _REST APIs_, los servidores _WebSocket_ y el streaming de pantalla
Aquí hay un script `setup.sh` de ejemplo:
```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"
```
Para un despliegue en producción (en un CTF real) quizás quieras aprovisionar un número predefinido de instancias de DroidGround de antemano o quizás quieras permitir que los usuarios generen instancias (con una limitación o tal vez asociar cada equipo/usuario con una instancia específica). Por esta razón también añadimos un simple [ejemplo de spawner](https://github.com/secforce/droidground/blob/main/examples/spawner).
Alternativamente, como se mencionó anteriormente, puedes crear un desafío donde la flag pueda ser exfiltrada mediante una solicitud de red y aprovechar la variable de entorno `DROIDGROUND_NUM_TEAMS` para evitar generar múltiples instancias (lo que podría ser costoso). La carpeta [net-multi-step](https://github.com/secforce/droidground/blob/main/examples/apps/net-multi-step) proporciona un buen ejemplo de cómo entregar este tipo de desafíos.
## 💡 Consejos
Aquí hay algunas sugerencias para configurar tu CTF de Android:
- Ten cuidado al habilitar el **Frida Full Mode**, el jugador tendrá control completo sobre el dispositivo (por eso creamos el **Frida Jail Mode** como se detalla en [Frida Library](https://github.com/secforce/droidground/blob/main/library)).
- Ten cuidado al habilitar la **Terminal**, el jugador tendrá control completo sobre el dispositivo.
- Ten cuidado al habilitar la característica de **Shutdown**.
- Si planeas hacer que la flag sea directamente visible en la UI, quizás quieras encontrar una forma de generar diferentes instancias (una para cada equipo/jugador)
Mientras pruebas la configuración antes de pasar a producción, podría ser útil obtener la **superficie de ataque** de la app objetivo. ¡Esto es algo que los jugadores no deberían ver porque es parte de su trabajo descubrir y analizar la superficie de ataque!
Por lo tanto, se proporciona un endpoint `GET` accesible en `/attackSurface` y protegido con un token (que debe usarse como valor del encabezado `Authorization`) que se genera aleatoriamente durante el arranque y se imprime en los logs (por lo tanto, accesible solo por sysadmins).
Si quieres usar tus propios scripts de Frida en modo jail, solo necesitas hacer bind-mount de la carpeta que los contiene dentro del contenedor Docker:
```yaml
volumes:
- <Frida library folder>:/droidground/library
```
Se requiere un archivo `library.json` (como el de [library](https://github.com/secforce/droidground/blob/main/library/library.json)) para indicar a la aplicación la lista de scripts disponibles.
## 🛠 Desarrollo
Ponerlo en marcha no debería ser demasiado difícil, pero antes de empezar deberías tener instaladas las siguientes herramientas:
- `frida` (solo si habilitas _Frida_)
- `node` (¡es una app Node, necesitas tenerlo!)
- `adb` (bueno, dependemos de él para comunicarnos con el dispositivo)
- _JDK_ (lo necesitas para compilar la app companion)
Después de eso, puedes simplemente ejecutar lo siguiente:
```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
```
Después de eso, solo necesitas establecer las variables de **env** y luego ejecutar `npm run dev` y estarás listo. ¡Feliz modo dev!
## 🤝 Contribuir
¡Las pull requests son bienvenidas! Por favor, abre primero un issue para discutir cambios importantes. Las ideas para nuevos flujos de trabajo de CTF o tipos de desafíos son especialmente apreciadas.
## 📚 Créditos
Desarrollado por [Angelo Delicato](https://github.com/thelicato) [@SECFORCE](https://www.secforce.com).
La sección _server_ depende en gran medida del increíble trabajo realizado por [@yume-chan](https://github.com/yume-chan/ya-webadb), probablemente esta app no existiría si no fuera por su increíble trabajo.
La app _companion_ está fuertemente basada en el [aya server](https://github.com/liriliri/aya/tree/master/server), que funciona de la misma manera que el [scrcpy server](https://github.com/Genymobile/scrcpy). Se pueden encontrar más detalles en el [README](https://github.com/secforce/droidground/blob/main/companion/README.md) específico.
## 🪪 Licencia
_DroidGround_ se publica bajo la [GPL-3.0 LICENSE](https://github.com/SECFORCE/droidground/blob/main/LICENSE)