Merge branch 'release/0.3.1'

Author: thelicato

.env.sample

@@ -24,4 +24,5 @@ DROIDGROUND_RESET_DISABLED=false # Feature enabled by default if not set otherwi
 DROIDGROUND_EXPLOIT_APP_DURATION=10 # The time (in seconds) the exploit app will be active before the target app is restarted. This field makes sense only if the App Manager is enabled. Default value is 10
 DROIDGROUND_NUM_TEAMS=0 # Number of teams playing, this enables the usage of team-based tokens/keys to lock down the usage of installed apps and log servers
 DROIDGROUND_TEAM_TOKEN_1=RANDOMSTRING # Token for team #1, this only makes sense if DROIDGROUND_NUM_TEAMS is higher than 0. If a team token is not explicitly defined it'll be randomly generated on boot and present in the output logs
-DROIDGROUND_IP_IFACE=eth0 # If this is set the UI will display the IP address associated with it. Useful to provide to the users the IP of the exploit server if dynamic. Empty by default
+DROIDGROUND_IP_STATIC=192.168.1.1 # Shows a static IP address in the Exploit Server page, this takes precedence over DROIDGROUND_IP_IFACE
+DROIDGROUND_IP_IFACE=eth0 # If this is set the UI will display the IP address associated with it. If an exact match is not found it will fallback to the first interface that starts with it. Useful to provide to the users the IP of the exploit server if dynamic. Empty by default

README.md

@@ -9,6 +9,7 @@
 <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="./docs/blackhat-2025.svg"></a>
 </p>
 
 In traditional **CTF challenges**, it's common to hide flags in files on a system, requiring attackers to exploit vulnerabilities to retrieve them. However, in the Android world, this approach doesn't work well. APK files are easily downloadable and reversible, so **placing a flag on the device usually makes it trivial** to extract using static analysis or emulator tricks. This severely limits the ability to create realistic, runtime-focused challenges.
@@ -56,6 +57,7 @@ DroidGround provides a rich set of server-controlled features.
 - **Terminal Access**
 - **APK Management**
 - **Logcat Viewer**
+- **Exploit Server** (if team mode is enabled)
 
 Almost all features are **modular** and defined via environment variables, ensuring precise control over the challenge scope.
 
@@ -103,7 +105,10 @@ The `.env.sample` file in the root directory is a good starting point. This is t
 | `DROIDGROUND_EXPLOIT_APP_DURATION`    | The time (in seconds) the exploit app will be active                              | `10`        |
 | `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_IFACE`                | The network interface for the displayed IP address. No IP is displayed 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                                | -           |
+
+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.
 
 The usage of the `DROIDGROUND_NUM_TEAMS` variable slightly changes the behaviour of the application under the hood. If this option is set:
 
@@ -147,6 +152,8 @@ echo "Install command executed"
 
 For a production deploy (in a real CTF) you may want to provision 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](./examples/spawner).
 
+Alternatively, as previously mentioned, you can create a challenge where the flag can be exfiltrated via a network request and leverage the `DROIDGROUND_NUM_TEAMS` env variable to avoid spawning multiple instances (which could be expensive). The [net-multi-step](./examples/apps/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:

docs/blackhat-2025.svg

@@ -0,0 +1,9 @@
+# Hidden Activity
+
+This is the simplest example ever to showcase basic _DroidGround's_ features.
+The target application is downloaded from the [samples](https://github.com/SECFORCE/droidground-samples) and it only contains an "hidden" exported activity that displays the flag.
+This "challenge" can be easily solved just by using the "Start Activity" feature in the "Overview" page.
+
+This example also showcases the `DROIDGROUND_BASE_PATH` env variable, which runs DroidGround on a subpath.
+
+Take a look at other examples for more realistic challenges.

examples/apps/hidden-activity/README.md

@@ -1,7 +1,7 @@
 # The ./init.d folder should contain the "setup.sh" and "reset.sh" scripts
 
 services:
-  docker-android:
+  android-device:
     image: halimqarroum/docker-android:api-33
     devices:
       - /dev/kvm
@@ -16,19 +16,5 @@ services:
       - 4242:4242
     volumes:
       - ./init.d:/init.d
-    environment:
-      - DROIDGROUND_BASE_PATH=/random1
-      - DROIDGROUND_APP_PACKAGE_NAME=com.droidground.hiddenactivity
-      - DROIDGROUND_ADB_HOST=localhost
-      - DROIDGROUND_ADB_PORT=5037
-      - DROIDGROUND_DEVICE_TYPE=network
-      - DROIDGROUND_DEVICE_HOST=docker-android
-      - DROIDGROUND_DEVICE_PORT=5555
-      - DROIDGROUND_INIT_SCRIPTS_FOLDER=/init.d
-      - DROIDGROUND_HOST=0.0.0.0
-      - DROIDGROUND_PORT=4242
-      - DROIDGROUND_APP_MANAGER_DISABLED=true
-      - DROIDGROUND_FRIDA_DISABLED=true
-      - DROIDGROUND_START_RECEIVER_DISABLED=true
-      - DROIDGROUND_START_SERVICE_DISABLED=true
-      - DROIDGROUND_TERMINAL_DISABLED=true
+    env_file:
+      - hidden-activity.env

examples/apps/hidden-activity/compose.docker-android.yaml

@@ -7,16 +7,17 @@
 # The ./init.d folder should contain the "setup.sh" and "reset.sh" scripts
 
 services:
-  redroid:
+  android-device:
     privileged: true
     volumes:
       - /dev/binder1:/dev/binder
       - /dev/binder2:/dev/hwbinder
       - /dev/binder3:/dev/vndbinder
     ports:
       - 5555:5555 # No need to expose this, but it's useful for debugging purposes
-    container_name: redroid14
+    container_name: redroid
     image: redroid/redroid:14.0.0-latest
+    command: ["ro.debuggable=0", "ro.boot.verifiedbootstate=orange"]
   droidground:
     build: ../../..
     container_name: droidground
@@ -25,18 +26,5 @@ services:
       - 4242:4242
     volumes:
       - ./init.d:/init.d
-    environment:
-      - DROIDGROUND_APP_PACKAGE_NAME=com.droidground.hiddenactivity
-      - DROIDGROUND_ADB_HOST=localhost
-      - DROIDGROUND_ADB_PORT=5037
-      - DROIDGROUND_DEVICE_TYPE=network
-      - DROIDGROUND_DEVICE_HOST=redroid
-      - DROIDGROUND_DEVICE_PORT=5555
-      - DROIDGROUND_INIT_SCRIPTS_FOLDER=/init.d
-      - DROIDGROUND_HOST=0.0.0.0
-      - DROIDGROUND_PORT=4242
-      - DROIDGROUND_APP_MANAGER_DISABLED=true
-      - DROIDGROUND_FRIDA_DISABLED=true
-      - DROIDGROUND_START_RECEIVER_DISABLED=true
-      - DROIDGROUND_START_SERVICE_DISABLED=true
-      - DROIDGROUND_TERMINAL_DISABLED=true
+    env_file:
+      - hidden-activity.env

examples/apps/hidden-activity/compose.redroid.debian.yaml

@@ -10,12 +10,13 @@
 # The ./init.d folder should contain the "setup.sh" and "reset.sh" scripts
 
 services:
-  redroid:
+  android-device:
     privileged: true
     ports:
       - 5555:5555 # No need to expose this, but it's useful for debugging purposes
-    container_name: redroid14
+    container_name: redroid
     image: redroid/redroid:14.0.0-latest
+    command: ["ro.debuggable=0", "ro.boot.verifiedbootstate=orange"]
   droidground:
     build: ../../..
     container_name: droidground
@@ -24,18 +25,5 @@ services:
       - 4242:4242
     volumes:
       - ./init.d:/init.d
-    environment:
-      - DROIDGROUND_APP_PACKAGE_NAME=com.droidground.hiddenactivity
-      - DROIDGROUND_ADB_HOST=localhost
-      - DROIDGROUND_ADB_PORT=5037
-      - DROIDGROUND_DEVICE_TYPE=network
-      - DROIDGROUND_DEVICE_HOST=redroid
-      - DROIDGROUND_DEVICE_PORT=5555
-      - DROIDGROUND_INIT_SCRIPTS_FOLDER=/init.d
-      - DROIDGROUND_HOST=0.0.0.0
-      - DROIDGROUND_PORT=4242
-      - DROIDGROUND_APP_MANAGER_DISABLED=true
-      - DROIDGROUND_FRIDA_DISABLED=true
-      - DROIDGROUND_START_RECEIVER_DISABLED=true
-      - DROIDGROUND_START_SERVICE_DISABLED=true
-      - DROIDGROUND_TERMINAL_DISABLED=true
+    env_file:
+      - hidden-activity.env

examples/apps/hidden-activity/compose.redroid.ubuntu.yaml

@@ -0,0 +1,15 @@
+DROIDGROUND_BASE_PATH=/random1
+DROIDGROUND_APP_PACKAGE_NAME=com.droidground.hiddenactivity
+DROIDGROUND_ADB_HOST=localhost
+DROIDGROUND_ADB_PORT=5037
+DROIDGROUND_DEVICE_TYPE=network
+DROIDGROUND_DEVICE_HOST=android-device
+DROIDGROUND_DEVICE_PORT=5555
+DROIDGROUND_INIT_SCRIPTS_FOLDER=/init.d
+DROIDGROUND_HOST=0.0.0.0
+DROIDGROUND_PORT=4242
+DROIDGROUND_APP_MANAGER_DISABLED=true
+DROIDGROUND_FRIDA_DISABLED=true
+DROIDGROUND_START_RECEIVER_DISABLED=true
+DROIDGROUND_START_SERVICE_DISABLED=true
+DROIDGROUND_TERMINAL_DISABLED=true

examples/apps/hidden-activity/hidden-activity.env

@@ -0,0 +1,6 @@
+# Multi Step
+
+This example showcases a more realistic intent-based CTF challenge where the user has to develop an exploit application in order to get the flag.
+The target application is downloaded from the [samples](https://github.com/SECFORCE/droidground-samples) and it contains an exported activity with a state machine within it. The goal of the player is to send the appropriate intents in the correct order to reach the final state and get the flag.
+
+This example showcases the _App Manager_ feature which allows to install and run exploit applications. Since the flag is actively displayed on the screen, challenges like this one would require the organizers to either queue the access to DroidGround or spawn different instances for each team. For a more cost-effective solution take a look at [net-multi-step](../net-multi-step/).

examples/apps/multi-step/README.md

@@ -1,7 +1,7 @@
 # The ./init.d folder should contain the "setup.sh" and "reset.sh" scripts
 
 services:
-  docker-android:
+  android-device:
     image: halimqarroum/docker-android:api-33
     devices:
       - /dev/kvm
@@ -16,18 +16,5 @@ services:
       - 4242:4242
     volumes:
       - ./init.d:/init.d
-    environment:
-      - DROIDGROUND_APP_PACKAGE_NAME=com.droidground.multistep
-      - DROIDGROUND_ADB_HOST=localhost
-      - DROIDGROUND_ADB_PORT=5037
-      - DROIDGROUND_DEVICE_TYPE=network
-      - DROIDGROUND_DEVICE_HOST=docker-android
-      - DROIDGROUND_DEVICE_PORT=5555
-      - DROIDGROUND_INIT_SCRIPTS_FOLDER=/init.d
-      - DROIDGROUND_HOST=0.0.0.0
-      - DROIDGROUND_PORT=4242
-      - DROIDGROUND_APP_MANAGER_DISABLED=true
-      - DROIDGROUND_FRIDA_DISABLED=true
-      - DROIDGROUND_START_RECEIVER_DISABLED=true
-      - DROIDGROUND_START_SERVICE_DISABLED=true
-      - DROIDGROUND_TERMINAL_DISABLED=true
+    env_file:
+      - multi-step.env