droidground - 为Android CTF挑战提供灵活的游乐场。

项目说明

<h1 align="center">
<br>
<img src="./logo.png" alt= "droidground" width="200px">
</h1>
<p align="center">
<b>DroidGround</b>
<p>

<p align="center">
<a href=" src="
<a href=" src="
<a href=" src="./docs/blackhat-2025.svg"></a>
<br />
<a href=" target="_blank">Website</a> |
<a href=" target="_blank">Demo</a>
</p>

In traditional CTF challenges, it's common to hide flags in files on a system, requiring attackers to exploit to retrieve them. However, in the Android world, this approach doesn't work well. APK files are easily downloadable and re, so placing a flag on the device usually makes it trivial to extract using static analysis or emulator tricks. This se limits the ability to create realistic, runtime-focused challenges.

_DroidGround_ is designed to solve this problem.

It is a custom-built platform for hosting Android mobile hacking challenges in a controlled and realistic en, where attackers are constrained just enough to require solving challenges in the intended way.

Importantly, participants may be jailed inside the app en. The modularity of the tool allows to set if the user can or cannot spawn a shell, read arbitrary files, or sideload tools. E can be setup so that the only way to retrieve the flag is through understanding and exploiting the app itself.

📋 Table of Contents

🧭 O

_DroidGround_ enables a wide of _Android_ challenges that are otherwise hard to implement in traditional CTF setups. For example, in a remote code execution (RCE) challenge, players might receive an APK for local analysis. After disco a , they can develop a Frida script and run it through DroidGround on the real target device to extract the flag from internal storage. Other challenge types can invol acti, custom broadcast intents, service exploitation, or dynamic analysis using preloaded tools.

With real-time device streaming, fine-grained control o, Frida integration, and customizable setup and reset scripts, DroidGround empowers CTF organizers to build secure, flexible, and realistic Android challenges that go far beyond what is typically possible.

✨ Features

DroidGround provides a rich set of ser features.

Almost all features are modular and defined , ensuring precise control over the challenge scope.

📸 Screenshots

| !Screenshot O | !Screenshot Start Activity |
| ------------------------------------------------------ | ----------------------------------------------------- |
| O | Start Activity |
| !Screenshot Frida Jailed Mode | !Screenshot Frida Full Mode |
| Frida Jailed Mode | Frida Full Mode |
| !Screenshot File Browser | !Screenshot App Manager |
| File Browser | App Manager |
| !Screenshot Terminal | !Screenshot Logs |
| Terminal | Logs |

⚙️ Configuration

The .en file in the root directory is a good starting point. This is the full list of all en currently supported:

| | Description | Default |
| ------------------------------------- | --------------------------------------------------------------------------------- | ----------- |
| DROIDGROUND_BASE_PATH | Path of the webapp (useful for hosting on subpaths) | - |
| DROIDGROUND_APP_PACKAGE_NAME | Package name of target app | - |
| DROIDGROUND_ADB_HOST | ADB host | localhost |
| DROIDGROUND_ADB_PORT | ADB port | 5037 |
| DROIDGROUND_ADB_SERIAL | Optional ADB device serial to connect to | - |
| DROIDGROUND_DE | usb or network | usb |
| DROIDGROUND_DE | IP of Android device (adb) (network mode only) | - |
| DROIDGROUND_DE | port of Android device (adb) (network mode only) | - |
| DROIDGROUND_INIT_SCRIPTS_FOLDER | Folder containing setup.sh and reset.sh | /init.d |
| DROIDGROUND_HOST | Bind address | 0.0.0.0 |
| DROIDGROUND_PORT | Bind port | 4242 |
| DROIDGROUND_RESTART_APP_DISABLED | Disable app restart | false |
| DROIDGROUND_APP_MANAGER_DISABLED | Disable app manager | false |
| DROIDGROUND_BUG_REPORT_DISABLED | Disable bugreport | false |
| DROIDGROUND_FILE_BROWSER_DISABLED | Disable file browser | false |
| DROIDGROUND_FRIDA_DISABLED | Disable Frida support | false |
| DROIDGROUND_FRIDA_TYPE | jail or full | jail |
| DROIDGROUND_FRIDA_INJECTION | server or gadget | server |
| DROIDGROUND_LOGCAT_DISABLED | Disable logcat | false |
| DROIDGROUND_REBOOT_ENABLED | Enable reboot | false |
| DROIDGROUND_SHUTDOWN_ENABLED | Enable shutdown | false |
| DROIDGROUND_START_ACTI | Disable startActivity | false |
| DROIDGROUND_START_RECEI | Disable broadcast | false |
| DROIDGROUND_START_SER | Disable startService | false |
| DROIDGROUND_TERMINAL_DISABLED | Disable terminal | false |
| DROIDGROUND_RESET_DISABLED | Disable reset | false |
| DROIDGROUND_SCRCPY_CONTROL_ENABLED | Enable mouse, touch, and keyboard input through the device screen | false |
| DROIDGROUND_SCRCPY_MAX_SIZE | Maximum video dimension in pixels; 0 keeps full device resolution | 1280 |
| DROIDGROUND_SCRCPY_MAX_FPS | Maximum video frame rate; 0 leaves it uncapped | 60 |
| DROIDGROUND_SCRCPY_ | Video bitrate in bits per second | 4000000 |
| DROIDGROUND_EXPLOIT_APP_DURATION | The time (in seconds) the exploit app will be active | 10 |
| DROIDGROUND_EXPLOIT_APP_MAX_SIZE | The max size (in MB) of the exploit app | 50 |
| DROIDGROUND_NUM_TEAMS | The number of teams playing simultaneously | - |
| DROIDGROUND_TEAM_TOKEN_<N> | The token for the nth team. Auto-generated if missing | - |
| DROIDGROUND_IP_STATIC | The static IP address to display. It takes precedence over DROIDGROUND_IP_IFACE | - |
| DROIDGROUND_IP_IFACE | The network interface for the displayed IP address | - |
| DROIDGROUND_LOGO_LINK | Optionally set the logo click-through link (e.g., your CTF main page) | - |

Set DROIDGROUND_SCRCPY_CONTROL_ENABLED=true and restart DroidGround to make the device screen interacti or tap the screen to focus it, then click, drag, swipe, use multiple touch points, scroll with the mouse wheel, or type. Right-click or press Escape for Android Back. Tab and Shift+Tab mo out of the screen. Input is shared by e the device, including in team mode. The default remains a screen. Text input uses scrcpy's Android key injection, so character support depends on the device's keyboard mapping.

The DROIDGROUND_IP_IFACE looks for an exact match first and fallbacks to the first interface that _starts with_ the provided value since Docker only allows to specify the network interface prefix within the container.

Screen streaming defaults to a maximum dimension of 1280 pixels, up to 60 fps, and 4 Mbps to reduce encoding, network, and browser work. This trades some fine detail for responsi in the embedded device view. Set DROIDGROUND_SCRCPY_MAX_SIZE=0 and DROIDGROUND_SCRCPY_=10000000 to restore the previous full-resolution quality settings. For slower connections or browsers, try a maximum size of 1024, 30 fps, and 2000000 bits per second. Restart DroidGround after changing these settings.

The browser uses WebCodecs when a and falls back to the software H.264 decoder otherwise. WebCodecs requires a secure context: use HTTPS for remote deployments (localhost also works). Plain HTTP on a remote IP or hostname uses software decoding. Slow skip to a fresh keyframe instead of accumulating a video backlog. If no keyframe arri 1.5 seconds, DroidGround requests a video refresh; this supports encoders such as ReDroid's OMX.google.h264.encoder, whose periodic I-frames are not necessarily independently decodable IDR frames. Refresh requests are shared across and may briefly refresh the screen for e. The ser an internal scrcpy control channel for video refreshes; mouse, touch, keyboard input, and automatic screen wake-up remain gated by DROIDGROUND_SCRCPY_CONTROL_ENABLED. See the WebCodecs specification and scrcpy video documentation for the underlying browser and video settings.

The usage of the DROIDGROUND_NUM_TEAMS slightly changes the behaviour of the application under the hood. If this option is set:

1. The exploit ser is enabled, allowing each team to be able to use their own (very simple) exploit server _team token_.
2. The team token will be required to install and run exploit apps. Each installed app will be tied to a team and other teams won't be able to run it.

This allows to share the same DroidGround instance with multiple teams in challenges where the flag can be exfiltrated via a network request. This massively reduces deploy costs of DroidGround for CTF competitions.

Furthermore, if the value is set to -1 it will enable the so-called Unlimited Teams mode. In this mode a button to generate a new _team token_ will be a in the _O page. All the DROIDGROUND_TEAM_TOKEN_<N> are ignored if this mode is enabled.

🧩 Use Cases

Here are some ways DroidGround can be used:

1. Hidden Activity: Find and launch an unexposed activity to see the flag (player's app contains a dummy flag).
2. RCE: The app is to RCE and the flag is stored on the device.
3. Frida Instrumentation: O a method and extract the flag from private memory using a script.

⚙️ Usage

A couple of sample _Docker Compose_ files are provided in the examples folder. They use apps from the DroidGround samples repo which will progressively be enhanced to showcase all the key features. They are also a good starting point to understand how to setup your own CTF.

On boot _DroidGround_ does the following:

1. Set up the connection with adb
2. Run the setup.sh in the folder specified by DROIDGROUND_INIT_SCRIPTS_FOLDER if present. This script can be used to install the target app and do e else that's needed to init the CTF (e.g. placing the flag in a known location)
3. (if _Frida_ is enabled) Download the correct frida-server based on the installed and the architecture of the device and start it
4. Run the target app (the one specified through DROIDGROUND_APP_PACKAGE_NAME). If the app is not installed _DroidGround_ will exit.
5. Setup the _REST APIs_, the _WebSocket_ servers and the display streaming

Here is a sample setup.sh script:

For a production deploy (in a real CTF) you may want to pro a pre-defined number of DroidGround instances beforehand or you may want to allow the users to spawn instances (with a limitation or maybe associate each team/user with a specific instance). For this reason we also added a simple spawner example.

Alternatively, as pre mentioned, you can create a challenge where the flag can be exfiltrated via a network request and le the DROIDGROUND_NUM_TEAMS en to avoid spawning multiple instances (which could be expensive). The net-multi-step folder provides a good example on how to deliver this type of challenges.

💡 Tips

Here are some suggestions for setting up your Android CTF:

While testing the setup before going in production it could be useful to get the attack surface of the target app. This is something that players shouldn't see because it's part of their job to discover and analyze the attack surface!

Therefore, a GET endpoint reachable at /attackSurface is provided and protected with a token (that needs to be used as the value of the Authorization header) that is randomly generated during the boot and printed in the logs (therefore accessible only by sysadmins).

If you want to use your own Frida scripts in jailed mode, you just need to bind-mount the folder that contains them into the Docker container:

A library.json file (like the one in the library) is required to instruct the application on the list of a scripts.

🛠 De

Getting it up & running shouldn't be too difficult, but before starting you should have the following tools installed:

After that you may just run the following:

After that you just need to set the env and then run npm run dev and you'll be good to go. Happy dev mode!

🤝 Contributing

Pull requests are welcome! Please open an issue first to discuss major changes. Ideas for new CTF workflows or challenge types are especially appreciated.

📚 Credits

De by Angelo Delicato .

The _server_ section heavily relies on the amazing work done by -chan, probably this app wouldn't exist if it wasn't for his amazing work.

The _companion_ app is heavily based on the aya server which works the same way as the scrcpy server. More details can be found in the specific README.

🪪 License

_DroidGround_ is released under the GPL-3.0 LICENSE

项目信息

开发语言：TypeScript

Star 数：118

技术要点

该项目属于CTF思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕A flexible playground for Android CTF challenges.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。