secforce/droidgroundUm playground flexível para desafios de 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">Website</a> |
<a href="https://droidground.com/demo" target="_blank">Demo</a>
</p>
Em **desafios CTF** tradicionais, é comum esconder flags em arquivos de um sistema, exigindo que os atacantes explorem vulnerabilidades para recuperá-las. No entanto, no mundo Android, essa abordagem não funciona bem. Arquivos APK são facilmente baixáveis e reversíveis, então **colocar uma flag no dispositivo geralmente torna trivial** extraí-la usando análise estática ou truques de emulador. Isso limita severamente a capacidade de criar desafios realistas focados em tempo de execução.
_DroidGround_ foi projetado para resolver esse problema.
É uma plataforma construída sob medida para hospedar desafios de hacking mobile Android em um ambiente **controlado** e **realista**, onde **os atacantes são restringidos apenas o suficiente** para exigir a resolução dos desafios da maneira pretendida.
Importante: os participantes podem ficar **presos dentro do ambiente do aplicativo**. A modularidade da ferramenta permite definir se o usuário pode ou não abrir um shell, ler arquivos arbitrários ou instalar ferramentas por sideload. Tudo pode ser configurado para que a única maneira de recuperar a flag seja por meio da compreensão e exploração do próprio aplicativo.
## 📋 Índice
- [🧭 Visão Geral](#-overview)
- [✨ Recursos](#-features)
- [📸 Capturas de Tela](#-screenshots)
- [⚙️ Configuração](#️-configuration)
- [🧩 Casos de Uso](#-use-cases)
- [⚙️ Uso](#️-usage)
- [💡 Dicas](#-tips)
- [🛠 Desenvolvimento](#-development)
- [🤝 Contribuição](#-contributing)
- [📚 Créditos](#-credits)
- [🪪 Licença](#-license)
## 🧭 Visão Geral
_DroidGround_ possibilita uma ampla variedade de desafios _Android_ que de outra forma seriam difíceis de implementar em configurações CTF tradicionais. Por exemplo, em um desafio de execução remota de código (RCE), os jogadores podem receber um APK para análise local. Após descobrir uma vulnerabilidade, eles podem desenvolver um script Frida e executá-lo através do DroidGround no dispositivo alvo real para extrair a flag do armazenamento interno. Outros tipos de desafio podem envolver atividades ocultas, intents de broadcast personalizados, exploração de serviços ou análise dinâmica usando ferramentas pré-carregadas.
Com streaming de dispositivo em tempo real, controle refinado sobre recursos, integração com Frida e scripts de configuração e reinicialização personalizáveis, o DroidGround capacita organizadores de CTF a criar desafios Android seguros, flexíveis e realistas que vão muito além do que normalmente é possível.
## ✨ Recursos
O DroidGround fornece um rico conjunto de recursos controlados pelo servidor.
- **Tela do Dispositivo em Tempo Real** (via `scrcpy`), com controle opcional de mouse, toque e teclado
- **Redefinir Estado do Desafio**
- **Reiniciar App / Iniciar Activity / Iniciar Service**
- **Enviar Broadcast Intent**
- **Desligar / Reiniciar Dispositivo**
- **Baixar Bugreport (bugreportz)**
- **Scripting com Frida**
- Executar a partir de biblioteca pré-carregada (modo restrito)
- Executar scripts arbitrários (modo completo)
- **Navegador de Arquivos**
- **Acesso ao Terminal**
- **Gerenciamento de APK**
- **Visualizador de Logcat**
- **Servidor de Exploit** (se o modo de equipe estiver habilitado)
Quase todos os recursos são **modulares** e definidos por meio de variáveis de ambiente, garantindo controle preciso sobre o escopo do desafio.
## 📸 Capturas de Tela
|  |  |
| ------------------------------------------------------ | ----------------------------------------------------- |
| Visão geral | Iniciar atividade |
|  |  |
| Modo Frida Jailed | Modo Frida Full |
|  |  |
| Navegador de arquivos | Gerenciador de apps |
|  |  |
| Terminal | Logs |
## ⚙️ Configuração
O arquivo `.env.sample` no diretório raiz é um bom ponto de partida. Esta é a lista completa de todas as variáveis de ambiente atualmente suportadas:
| Variável | Descrição | Padrão |
| ------------------------------------- | --------------------------------------------------------------------------------- | ----------- |
| `DROIDGROUND_BASE_PATH` | Caminho da webapp (útil para hospedar em subcaminhos) | - |
| `DROIDGROUND_APP_PACKAGE_NAME` | Nome do pacote do app alvo | - |
| `DROIDGROUND_ADB_HOST` | Host do ADB | `localhost` |
| `DROIDGROUND_ADB_PORT` | Porta do ADB | `5037` |
| `DROIDGROUND_ADB_SERIAL` | Serial opcional do dispositivo ADB ao qual se conectar | - |
| `DROIDGROUND_DEVICE_TYPE` | `usb` ou `network` | `usb` |
| `DROIDGROUND_DEVICE_HOST` | IP do dispositivo Android (`adb`) (apenas modo network) | - |
| `DROIDGROUND_DEVICE_PORT` | porta do dispositivo Android (`adb`) (apenas modo network) | - |
| `DROIDGROUND_INIT_SCRIPTS_FOLDER` | Pasta contendo `setup.sh` e `reset.sh` | `/init.d` |
| `DROIDGROUND_HOST` | Endereço de bind | `0.0.0.0` |
| `DROIDGROUND_PORT` | Porta de bind | `4242` |
| `DROIDGROUND_RESTART_APP_DISABLED` | Desabilita a reinicialização do app | `false` |
| `DROIDGROUND_APP_MANAGER_DISABLED` | Desabilita o gerenciador de apps | `false` |
| `DROIDGROUND_BUG_REPORT_DISABLED` | Desabilita o bugreport | `false` |
| `DROIDGROUND_FILE_BROWSER_DISABLED` | Desabilita o navegador de arquivos | `false` |
| `DROIDGROUND_FRIDA_DISABLED` | Desabilita o suporte ao Frida | `false` |
| `DROIDGROUND_FRIDA_TYPE` | `jail` ou `full` | `jail` |
| `DROIDGROUND_FRIDA_INJECTION` | `server` ou `gadget` | `server` |
| `DROIDGROUND_LOGCAT_DISABLED` | Desabilita o logcat | `false` |
| `DROIDGROUND_REBOOT_ENABLED` | Habilita a reinicialização | `false` |
| `DROIDGROUND_SHUTDOWN_ENABLED` | Habilita o desligamento | `false` |
| `DROIDGROUND_START_ACTIVITY_DISABLED` | Desabilita o startActivity | `false` |
| `DROIDGROUND_START_RECEIVER_DISABLED` | Desabilita o broadcast | `false` |
| `DROIDGROUND_START_SERVICE_DISABLED` | Desabilita o startService | `false` |
| `DROIDGROUND_TERMINAL_DISABLED` | Desabilita o terminal | `false` |
| `DROIDGROUND_RESET_DISABLED` | Desabilita o reset | `false` |
| `DROIDGROUND_SCRCPY_CONTROL_ENABLED` | Habilita entrada de mouse, toque e teclado através da tela do dispositivo | `false` |
| `DROIDGROUND_SCRCPY_MAX_SIZE` | Dimensão máxima do vídeo em pixels; `0` mantém a resolução total do dispositivo | `1280` |
| `DROIDGROUND_SCRCPY_MAX_FPS` | Taxa máxima de quadros do vídeo; `0` deixa-a sem limite | `60` |
| `DROIDGROUND_SCRCPY_VIDEO_BIT_RATE` | Bitrate do vídeo em bits por segundo | `4000000` |
| `DROIDGROUND_EXPLOIT_APP_DURATION` | O tempo (em segundos) durante o qual o aplicativo de exploit ficará ativo | `10` |
| `DROIDGROUND_EXPLOIT_APP_MAX_SIZE` | O tamanho máximo (em MB) do aplicativo de exploit | `50` |
| `DROIDGROUND_NUM_TEAMS` | O número de equipes jogando simultaneamente | - |
| `DROIDGROUND_TEAM_TOKEN_<N>` | O token da enésima equipe. Gerado automaticamente se estiver ausente | - |
| `DROIDGROUND_IP_STATIC` | O endereço IP estático a ser exibido. Tem precedência sobre `DROIDGROUND_IP_IFACE` | - |
| `DROIDGROUND_IP_IFACE` | A interface de rede para o endereço IP exibido | - |
| `DROIDGROUND_LOGO_LINK` | Define opcionalmente o link de clique do logotipo (por exemplo, sua página principal do CTF) | - |
Defina `DROIDGROUND_SCRCPY_CONTROL_ENABLED=true` e reinicie o DroidGround para tornar a tela do dispositivo interativa. Clique ou toque na tela para focá-la, depois clique, arraste, deslize, use múltiplos pontos de toque, role com a roda do mouse ou digite. Clique com o botão direito ou pressione Escape para o Android Back. Tab e Shift+Tab movem o foco para fora da tela. A entrada é compartilhada por todos que visualizam o dispositivo; durante uma execução de exploit de uma equipe, apenas visualizadores autenticados como aquela equipe podem visualizá-lo ou controlá-lo. O padrão continua sendo uma tela somente de visualização. A entrada de texto usa a injeção de teclas do Android do scrcpy, portanto o suporte a caracteres depende do mapeamento de teclado do dispositivo.
A variável `DROIDGROUND_IP_IFACE` procura primeiro por uma correspondência exata e, como fallback, usa a primeira interface que _começa com_ o valor fornecido, já que o Docker só permite especificar o **prefixo** da interface de rede dentro do contêiner.
A transmissão da tela usa por padrão uma dimensão máxima de 1280 pixels, até 60 fps e 4 Mbps para reduzir o trabalho de codificação, rede e navegador. Isso troca um pouco de detalhe fino por responsividade na visualização incorporada do dispositivo. Defina `DROIDGROUND_SCRCPY_MAX_SIZE=0` e `DROIDGROUND_SCRCPY_VIDEO_BIT_RATE=10000000` para restaurar as configurações anteriores de qualidade em resolução total. Para conexões ou navegadores mais lentos, tente um tamanho máximo de `1024`, `30` fps e `2000000` bits por segundo. Reinicie o DroidGround após alterar essas configurações.
O navegador usa WebCodecs quando disponível e, caso contrário, recorre ao decodificador H.264 por software. O WebCodecs exige um contexto seguro: use HTTPS para implantações remotas (localhost também funciona). HTTP simples em um IP ou hostname remoto usa decodificação por software. Visualizadores lentos pulam para um novo keyframe em vez de acumular um atraso de vídeo. Se nenhum keyframe chegar em 1,5 segundos, o DroidGround solicita uma atualização de vídeo; isso dá suporte a codificadores como o `OMX.google.h264.encoder` do ReDroid, cujos I-frames periódicos não são necessariamente quadros IDR decodificáveis de forma independente. As solicitações de atualização são compartilhadas entre os visualizadores e podem atualizar brevemente a tela para todos. O servidor mantém um canal de controle interno do scrcpy para atualizações de vídeo; entrada de mouse, toque e teclado, além do despertar automático da tela, continuam condicionados por `DROIDGROUND_SCRCPY_CONTROL_ENABLED`. Consulte a [especificação WebCodecs](https://www.w3.org/TR/webcodecs/#videodecoder-interface) e a [documentação de vídeo do scrcpy](https://github.com/Genymobile/scrcpy/blob/master/doc/video.md) para as configurações subjacentes de navegador e vídeo.
O uso da variável `DROIDGROUND_NUM_TEAMS` altera ligeiramente o comportamento da aplicação nos bastidores. Se esta opção estiver definida:
1. O recurso de servidor de exploit é habilitado, permitindo que cada equipe use seu próprio (muito simples) servidor de exploit por meio do seu **_team token_**.
2. O team token será **obrigatório** para instalar e executar apps de exploit. Cada app instalado ficará vinculado a uma equipe e as outras equipes não poderão executá-lo.
3. Enquanto o app de exploit de uma equipe estiver em execução, outras equipes e visualizadores sem token verão uma tela preta explicando que o exploit de outra equipe está em execução. O servidor retém o vídeo e rejeita a entrada deles no dispositivo. A tela compartilhada é retomada após o app alvo reiniciar. Insira seu token em **Team token for display** abaixo do dispositivo para assistir às execuções da sua equipe; iniciar um exploit pela interface também autentica automaticamente a tela daquele navegador. Os tokens são enviados pelo WebSocket em vez de na sua URL e são mantidos em memória para a página atual. Isso também se aplica no modo Unlimited Teams. Sem o modo de equipes, a tela permanece compartilhada.
Isso permite compartilhar a mesma instância do DroidGround com várias equipes em desafios nos quais a flag pode ser exfiltrada por meio de uma requisição de rede. Isso **reduz drasticamente os custos de implantação do DroidGround** para competições de CTF.
Além disso, se o valor for definido como `-1`, será habilitado o chamado modo **Unlimited Teams**. Nesse modo, um botão para gerar um novo **_team token_** ficará disponível na página _Overview_. Todas as variáveis `DROIDGROUND_TEAM_TOKEN_<N>` são ignoradas se esse modo estiver habilitado.
## 🧩 Casos de Uso
Aqui estão algumas formas de usar o DroidGround:
1. **Atividade Oculta**: Encontre e inicie uma atividade não exposta para ver a flag (o aplicativo do jogador contém uma flag fictícia).
2. **RCE**: O aplicativo é vulnerável a RCE e a flag está armazenada no dispositivo.
3. **Instrumentação Frida**: Sobrecarregue um método e extraia a flag da memória privada usando um script.
## ⚙️ Uso
Alguns arquivos _Docker Compose_ de exemplo são fornecidos na pasta [examples](https://github.com/secforce/droidground/blob/main/examples/apps). Eles usam aplicativos do [repositório de amostras do DroidGround](https://github.com/SECFORCE/droidground-samples), que será progressivamente aprimorado para demonstrar todos os recursos principais. Eles também são um bom ponto de partida para entender como configurar seu próprio CTF.
Na inicialização, o _DroidGround_ faz o seguinte:
1. Configura a conexão com o `adb`
2. Executa o `setup.sh` na pasta especificada por `DROIDGROUND_INIT_SCRIPTS_FOLDER`, se presente. Este script pode ser usado para instalar o aplicativo alvo e fazer tudo o mais que for necessário para inicializar o CTF (por exemplo, colocar a flag em um local conhecido)
3. (se o _Frida_ estiver habilitado) Baixa o `frida-server` correto com base na versão instalada e na arquitetura do dispositivo e o inicia
4. Executa o aplicativo alvo (o especificado por meio de `DROIDGROUND_APP_PACKAGE_NAME`). Se o aplicativo não estiver instalado, o _DroidGround_ será encerrado.
5. Configura as _REST APIs_, os servidores _WebSocket_ e a transmissão da tela
Aqui está um exemplo 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"
```
Para uma implantação em produção (em um CTF real), você pode querer provisionar previamente um número predefinido de instâncias do DroidGround ou pode querer permitir que os usuários criem instâncias (com uma limitação ou talvez associar cada equipe/usuário a uma instância específica). Por esse motivo, também adicionamos um simples [exemplo de spawner](https://github.com/secforce/droidground/blob/main/examples/spawner).
Alternativamente, como mencionado anteriormente, você pode criar um desafio em que a flag possa ser exfiltrada por meio de uma requisição de rede e aproveitar a variável de ambiente `DROIDGROUND_NUM_TEAMS` para evitar a criação de múltiplas instâncias (o que poderia ser caro). A pasta [net-multi-step](https://github.com/secforce/droidground/blob/main/examples/apps/net-multi-step) fornece um bom exemplo de como entregar esse tipo de desafio.
## 💡 Dicas
Aqui estão algumas sugestões para configurar seu CTF Android:
- Tenha cuidado ao habilitar o **Frida Full Mode**, pois o jogador terá controle total sobre o dispositivo (é por isso que criamos o **Frida Jail Mode**, conforme detalhado em [Frida Library](https://github.com/secforce/droidground/blob/main/library)).
- Tenha cuidado ao habilitar o **Terminal**, pois o jogador terá controle total sobre o dispositivo.
- Tenha cuidado ao habilitar o recurso **Shutdown**.
- Se você planeja tornar a flag diretamente visível na interface do usuário, talvez queira encontrar uma forma de criar instâncias diferentes (uma para cada equipe/jogador)
Ao testar a configuração antes de ir para produção, pode ser útil obter a **superfície de ataque** do aplicativo alvo. Isso é algo que os jogadores não devem ver, pois faz parte do trabalho deles descobrir e analisar a superfície de ataque!
Portanto, é fornecido um endpoint `GET` acessível em `/attackSurface`, protegido com um token (que precisa ser usado como valor do cabeçalho `Authorization`) gerado aleatoriamente durante a inicialização e impresso nos logs (portanto, acessível apenas por sysadmins).
Se você quiser usar seus próprios scripts Frida no modo jailed, basta fazer bind-mount da pasta que os contém no contêiner Docker:
```yaml
volumes:
- <Frida library folder>:/droidground/library
```
Um arquivo `library.json` (como o que está em [library](https://github.com/secforce/droidground/blob/main/library/library.json)) é necessário para instruir a aplicação sobre a lista de scripts disponíveis.
## 🛠 Desenvolvimento
Colocá-lo em funcionamento não deve ser muito difícil, mas antes de começar você deve ter as seguintes ferramentas instaladas:
- `frida` (apenas se você habilitar o _Frida_)
- `node` (é um aplicativo Node, você precisa tê-lo!)
- `adb` (bem, dependemos dele para conversar com o dispositivo)
- _JDK_ (você precisa dele para compilar o aplicativo companion)
Depois disso, você pode simplesmente executar o seguinte:
```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
```
Depois disso, você só precisa definir as variáveis de **env** e então executar `npm run dev` e estará pronto para começar. Bom modo dev!
## 🤝 Contribuindo
Pull requests são bem-vindos! Por favor, abra uma issue primeiro para discutir mudanças importantes. Ideias para novos fluxos de trabalho de CTF ou tipos de desafios são especialmente apreciadas.
## 📚 Créditos
Desenvolvido por [Angelo Delicato](https://github.com/thelicato) [@SECFORCE](https://www.secforce.com).
A seção _server_ depende fortemente do incrível trabalho feito por [@yume-chan](https://github.com/yume-chan/ya-webadb); provavelmente este aplicativo não existiria se não fosse pelo seu incrível trabalho.
O aplicativo _companion_ é fortemente baseado no [aya server](https://github.com/liriliri/aya/tree/master/server), que funciona da mesma forma que o [scrcpy server](https://github.com/Genymobile/scrcpy). Mais detalhes podem ser encontrados no [README](https://github.com/secforce/droidground/blob/main/companion/README.md) específico.
## 🪪 Licença
_DroidGround_ é distribuído sob a [GPL-3.0 LICENSE](https://github.com/SECFORCE/droidground/blob/main/LICENSE)