
Un 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">Sitio web</a> |
<a href="https://droidground.com/demo" target="_blank">Demo</a>
</p>
En los **retos CTF** tradicionales, es común ocultar las flags en archivos del 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 se pueden descargar y revertir fácilmente, 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 retos realistas centrados en el tiempo de ejecución.
_DroidGround_ está diseñado para resolver este problema.
Es una plataforma de creación propia para alojar retos de hacking móvil en Android en un entorno **controlado** y **realista**, donde **los atacantes están restringidos lo justo** para exigir que resuelvan los retos de la forma prevista.
Es importante destacar que los participantes pueden estar **confinados dentro del entorno de la aplicación**. 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 se puede configurar para que la única forma de recuperar la flag sea comprendiendo y explotando la propia aplicación.
## 📋 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 retos de _Android_ que de otro modo son difíciles de implementar en configuraciones CTF tradicionales. Por ejemplo, en un reto de ejecución remota de código (RCE), los jugadores podrían recibir un APK para su análisis local. Tras 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 retos pueden implicar actividades ocultas, intents de broadcast personalizados, explotación de servicios o análisis dinámico mediante herramientas precargadas.
Con la transmisión del dispositivo en tiempo real, el control detallado de las funcionalidades, la integración con Frida y scripts de configuración y reinicio personalizables, DroidGround permite a los organizadores de CTF crear retos de Android seguros, flexibles y realistas que van mucho más allá de lo que suele ser posible.
## ✨ Características
DroidGround proporciona un amplio conjunto de funcionalidades controladas por el servidor.
- **Pantalla del dispositivo en tiempo real** (mediante `scrcpy`), con control opcional de ratón, táctil y teclado
- **Restablecer el estado del reto**
- **Reiniciar la aplicación / Iniciar actividad / Iniciar servicio**
- **Enviar intent de broadcast**
- **Apagar / Reiniciar el dispositivo**
- **Descargar bugreport (bugreportz)**
- **Scripting con Frida**
- Ejecutar desde la biblioteca precargada (modo confinado)
- Ejecutar scripts arbitrarios (modo completo)
- **Navegador de archivos**
- **Acceso a terminal**
- **Gestión de APK**
- **Visor de Logcat**
- **Servidor de exploits** (si el modo equipo está habilitado)
Casi todas las funcionalidades son **modulares** y se definen mediante variables de entorno, lo que garantiza un control preciso del alcance del reto.
## 📸 Capturas de pantalla
|  |  |
| ------------------------------------------------------ | ----------------------------------------------------- |
| Vista general | Iniciar actividad |
|  |  |
| Modo Frida Jailed | Modo Frida Full |
|  |  |
| Explorador de archivos | Gestor de aplicaciones |
|  |  |
| Terminal | Registros |
## ⚙️ 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 actualmente compatibles:
| Variable | Description | Default |
| ------------------------------------- | --------------------------------------------------------------------------------- | ----------- |
| `DROIDGROUND_BASE_PATH` | Ruta de la aplicación web (útil para alojarla en subrutas) | - |
| `DROIDGROUND_APP_PACKAGE_NAME` | Nombre del paquete de la aplicación 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 en modo network) | - |
| `DROIDGROUND_DEVICE_PORT` | Puerto del dispositivo Android (`adb`) (solo en 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 el reinicio de la aplicación | `false` |
| `DROIDGROUND_APP_MANAGER_DISABLED` | Deshabilitar el gestor de aplicaciones | `false` |
| `DROIDGROUND_BUG_REPORT_DISABLED` | Deshabilitar el informe de errores | `false` |
| `DROIDGROUND_FILE_BROWSER_DISABLED` | Deshabilitar el explorador de archivos | `false` |
| `DROIDGROUND_FRIDA_DISABLED` | Deshabilitar la compatibilidad con 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 el reinicio | `false` |
| `DROIDGROUND_SHUTDOWN_ENABLED` | Habilitar el apagado | `false` |
| `DROIDGROUND_START_ACTIVITY_DISABLED` | Deshabilitar startActivity | `false` |
| `DROIDGROUND_START_RECEIVER_DISABLED` | Deshabilitar la difusión (broadcast) | `false` |
| `DROIDGROUND_START_SERVICE_DISABLED` | Deshabilitar startService | `false` |
| `DROIDGROUND_TERMINAL_DISABLED` | Deshabilitar la terminal | `false` |
| `DROIDGROUND_RESET_DISABLED` | Deshabilitar el restablecimiento | `false` |
| `DROIDGROUND_SCRCPY_CONTROL_ENABLED` | Habilitar la 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 máxima de fotogramas 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 que juegan 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` | Opcionalmente establece 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 interactiva la pantalla del dispositivo. 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 Android Back. Tab y Shift+Tab mueven el foco fuera de la pantalla. La entrada es compartida por todos los que visualizan el dispositivo; durante una ejecución de exploit en equipo, solo los espectadores autenticados como ese equipo pueden verla o controlarla. 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 la compatibilidad de caracteres depende de la asignación de teclado del dispositivo.
`DROIDGROUND_IP_IFACE` busca primero una coincidencia exacta y, en su defecto, 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.
La transmisión de pantalla tiene por defecto 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 en favor de la 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 con un tamaño máximo de `1024`, `30` fps y `2000000` bits por segundo. Reinicia DroidGround después de cambiar estas opciones.
El navegador utiliza WebCodecs cuando está disponible y, en caso contrario, recurre al decodificador H.264 por software. WebCodecs requiere un contexto seguro: usa HTTPS para despliegues remotos (localhost también funciona). HTTP sin cifrar en una IP o nombre de host remoto utiliza decodificación por software. Los espectadores lentos saltan a un keyframe nuevo en lugar de acumular un retraso de vídeo. Si no llega ningún keyframe en 1,5 segundos, DroidGround solicita una actualización de vídeo; esto es compatible con codificadores como `OMX.google.h264.encoder` de ReDroid, cuyos I-frames periódicos no son necesariamente frames IDR decodificables de forma independiente. Las solicitudes de actualización se comparten entre los espectadores 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 y teclado, así como 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. Se habilita la función de servidor de exploits, permitiendo que cada equipo pueda usar su propio servidor de exploits (muy simple) mediante su **_token de equipo_**.
2. El token de equipo será **obligatorio** para instalar y ejecutar aplicaciones de exploit. Cada aplicación instalada quedará vinculada a un equipo y los demás equipos no podrán ejecutarla.
3. Mientras se ejecuta la aplicación de exploit de un equipo, los demás equipos y los espectadores sin token ven una pantalla negra que explica que se está ejecutando el exploit de otro equipo. El servidor retiene el vídeo y rechaza su entrada del dispositivo. La pantalla compartida se reanuda después de que la aplicación objetivo se reinicie. Introduce tu token en **Team token for display** debajo del dispositivo para ver las ejecuciones de tu equipo; iniciar un exploit desde la interfaz también autentica automáticamente la pantalla de ese navegador. Los tokens se envían a través del WebSocket en lugar de en su URL y se mantienen en memoria para la página actual. Esto también se aplica en el modo Unlimited Teams. Sin el modo de equipos, la pantalla permanece compartida.
Esto permite compartir la misma instancia de DroidGround con varios equipos en retos donde la flag puede exfiltrarse mediante una solicitud de red. Esto **reduce enormemente los costes de despliegue de DroidGround** para competiciones CTF.
Además, si el valor se establece en `-1`, se habilitará el llamado modo **Unlimited Teams**. En este modo, habrá un botón disponible en la página _Overview_ para generar un nuevo **_token de equipo_**. 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**: Encuentra y lanza una actividad no expuesta para ver la flag (la aplicación del jugador contiene una flag ficticia).
2. **RCE**: La aplicación es vulnerable a RCE y la flag está almacenada en el dispositivo.
3. **Instrumentación con Frida**: Sobrecarga un método y extrae 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). Utilizan aplicaciones del [repositorio de ejemplos de DroidGround](https://github.com/SECFORCE/droidground-samples), que se irá mejorando 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 existe. Este script se puede usar para instalar la aplicación objetivo y hacer todo lo demás que sea necesario para inicializar el CTF (por ejemplo, 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 aplicación objetivo (la especificada mediante `DROIDGROUND_APP_PACKAGE_NAME`). Si la aplicación no está instalada, _DroidGround_ finalizará.
5. Configura las _REST APIs_, los servidores _WebSocket_ y la transmisión de la 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) es posible que quieras aprovisionar de antemano un número predefinido de instancias de DroidGround o que quieras permitir a los usuarios generar instancias (con una limitación o quizás asociar cada equipo/usuario con una instancia específica). Por este motivo también añadimos un sencillo [ejemplo de generador](https://github.com/secforce/droidground/blob/main/examples/spawner).
Alternativamente, como se mencionó anteriormente, puedes crear un desafío en el que 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 cual podría resultar costoso). La carpeta [net-multi-step](https://github.com/secforce/droidground/blob/main/examples/apps/net-multi-step) proporciona un buen ejemplo sobre cómo entregar este tipo de desafíos.
## 💡 Consejos
Aquí tienes algunas sugerencias para configurar tu CTF de Android:
- Ten cuidado al habilitar el **Modo Completo de Frida**, el jugador tendrá control total sobre el dispositivo (por eso creamos el **Modo Jail de Frida** como se detalla en [Biblioteca Frida](https://github.com/secforce/droidground/blob/main/library)).
- Ten cuidado al habilitar la **Terminal**, el jugador tendrá control total sobre el dispositivo.
- Ten cuidado al habilitar la función de **Apagado**.
- Si planeas hacer que la flag sea directamente visible en la interfaz de usuario, es posible que 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 resultarte útil obtener la **superficie de ataque** de la aplicación objetivo. ¡Esto es algo que los jugadores no deberían ver, ya que forma 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 registros (por lo tanto, accesible solo por los administradores del sistema).
Si quieres usar tus propios scripts de Frida en modo jail, solo necesitas montar mediante bind la carpeta que los contiene en el contenedor de Docker:
```yaml
volumes:
- <Frida library folder>:/droidground/library
```
Se requiere un archivo `library.json` (como el que se encuentra en la [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 y funcionando 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 aplicación Node, ¡necesitas tenerlo!)
- `adb` (bueno, dependemos de él para comunicarnos con el dispositivo)
- _JDK_ (lo necesitas para compilar la aplicación complementaria)
Después de eso, simplemente puedes 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 configurar las variables de **env** y luego ejecutar `npm run dev` y estarás listo para comenzar. ¡Feliz modo dev!
## 🤝 Contribuir
¡Las pull requests son bienvenidas! Por favor, abre primero un issue para discutir cambios importantes. Se agradecen especialmente las ideas para nuevos flujos de trabajo de CTF o tipos de desafíos.
## 📚 Créditos
Desarrollado por [Angelo Delicato](https://github.com/thelicato) [@SECFORCE](https://www.secforce.com).
La sección _server_ se apoya en gran medida en el increíble trabajo realizado por [@yume-chan](https://github.com/yume-chan/ya-webadb); probablemente esta aplicación no existiría si no fuera por su increíble trabajo.
La aplicación _companion_ está basada en gran medida 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 distribuye bajo la [GPL-3.0 LICENSE](https://github.com/SECFORCE/droidground/blob/main/LICENSE)