Merge branch 'release/1.0.0'

Author: thelicato

.env.sample

@@ -23,6 +23,7 @@ DROIDGROUND_START_SERVICE_DISABLED=false # Feature enabled by default if not set
 DROIDGROUND_TERMINAL_DISABLED=false # Feature enabled by default if not set otherwise
 DROIDGROUND_RESET_DISABLED=false # Feature enabled by default if not set otherwise
 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_EXPLOIT_APP_MAX_SIZE=50 # The max size (in MB) of the exploit app. This field makes sense only if the App Manager is enabled. Default value is 50
 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_STATIC=192.168.1.1 # Shows a static IP address in the Exploit Server page, this takes precedence over DROIDGROUND_IP_IFACE

README.md

@@ -10,6 +10,9 @@
     <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>
+    <br />
+    <a href="https://droidground.com" target="_blank">Website</a> |
+    <a href="https://droidground.com/demo" target="_blank">Demo</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.
@@ -104,6 +107,7 @@ The `.env.sample` file in the root directory is a good starting point. This is t
 | `DROIDGROUND_TERMINAL_DISABLED`       | Disable terminal                                                                  | `false`     |
 | `DROIDGROUND_RESET_DISABLED`          | Disable reset                                                                     | `false`     |
 | `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` | -           |

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "droidground",
-  "version": "0.3.5",
+  "version": "1.0.0",
   "type": "module",
   "author": "Angelo Delicato",
   "scripts": {

package.json

@@ -508,10 +508,16 @@ class APIController {
       }
 
       const manager = ManagerSingleton.getInstance();
+      const features = manager.getConfig().features;
+
+      // Check if file size exceeds max size
+      if (req.file.size > features.exploitAppMaxSize * 1024 * 1024) {
+        throw new Error(`Exploit App size exceeds the limit of ${features.exploitAppMaxSize} MB.`);
+      }
 
       // Check if teamToken is needed and valid
       if (
-        manager.getConfig().features.teamModeEnabled &&
+        features.teamModeEnabled &&
         (!Object.keys(req.body).includes("teamToken") || !manager.isTeamTokenValid(req.body.teamToken))
       ) {
         throw new Error("Missing or invalid Team Token.");
@@ -550,7 +556,7 @@ class APIController {
 
       manager.exploitApps.push(packageName);
       // Duplicate but it shouldn't be a big problem
-      if (manager.getConfig().features.teamModeEnabled) {
+      if (features.teamModeEnabled) {
         manager.linkExploitAppToTeam(req.body.teamToken, packageName);
       }
 

src/server/api/controller.ts

@@ -10,7 +10,7 @@ import { ScrcpyMediaStreamConfigurationPacket } from "@yume-chan/scrcpy";
 import { AdbServerNodeTcpConnector } from "@yume-chan/adb-server-node-tcp";
 import Logger from "@shared/logger";
 import { randomString, sleep } from "@shared/helpers";
-import { DroidGroundConfig, DroidGroundTeam, FridaState, StreamMetadata } from "@shared/types";
+import { DroidGroundConfig, DroidGroundTeam, FridaState, StreamMetadata, DroidGroundFrame } from "@shared/types";
 import { AppStatus, WebsocketClient } from "@server/utils/types";
 import { setupFrida } from "@server/utils/frida";
 import { setupScrcpy } from "@server/utils/scrcpy";
@@ -44,11 +44,17 @@ export class ManagerSingleton {
   public exploitApps: string[] = [];
   // Exploit App Run Queue
   public queue;
+  // Last Scrcpy keyframe
+  public lastKeyframe: DroidGroundFrame | null = null;
+  public lastFrame: DroidGroundFrame | null = null;
 
   private constructor() {
     // private constructor prevents direct instantiation
     const port: any = process.env.DROIDGROUND_ADB_PORT ?? "";
     const exploitAppDuration: any = process.env.DROIDGROUND_EXPLOIT_APP_DURATION ?? "";
+    const exploitAppmaxSizeEnv: any = process.env.DROIDGROUND_EXPLOIT_APP_MAX_SIZE ?? "";
+    const exploitAppMaxSize: number =
+      isNaN(exploitAppmaxSizeEnv) || exploitAppmaxSizeEnv.trim().length === 0 ? 50 : parseInt(exploitAppmaxSizeEnv);
     // Check if IP address should be displayed
     const ipStatic = process.env.DROIDGROUND_IP_STATIC ?? undefined;
     const iface = process.env.DROIDGROUND_IP_IFACE ?? "";
@@ -92,6 +98,7 @@ export class ManagerSingleton {
         fridaType: process.env.DROIDGROUND_FRIDA_TYPE === "full" ? "full" : "jail",
         exploitAppDuration:
           isNaN(exploitAppDuration) || exploitAppDuration.trim().length === 0 ? 10 : parseInt(exploitAppDuration),
+        exploitAppMaxSize: exploitAppMaxSize,
         ipAddress: `${ipAddress}:${backendPort}`,
         logoLink: parseValidUrl(process.env.DROIDGROUND_LOGO_LINK ?? ""),
       },

src/server/manager.ts

@@ -105,6 +105,11 @@ export const setupScrcpy = async () => {
                   keyframe: packet.keyframe,
                   pts: packet.pts ? packet.pts.toString() : null,
                 };
+                // Store frame
+                singleton.lastFrame = { metadata: metadata, data: packet.data };
+                if (metadata.keyframe) {
+                  singleton.lastKeyframe = { metadata: metadata, data: packet.data };
+                }
                 broadcastForPhase(wsStreamingClients, StreamingPhase.RENDER, {
                   type: WSMessageType.DATA,
                   metadata: metadata,

src/server/utils/scrcpy.ts

@@ -35,10 +35,17 @@ export const setupScrcpyWss = (wssStreaming: WebSocketServer) => {
           }
           break;
         case WSMessageType.CONFIGURATION_ACK:
-          const nextState: StreamingPhase =
+          let nextState: StreamingPhase =
             singleton.sharedVideoMetadata?.hardwareType === "hardware"
               ? StreamingPhase.KEYFRAME
               : StreamingPhase.RENDER;
+          // Send last frames if available
+          if (nextState == StreamingPhase.RENDER && singleton.lastFrame) {
+            sendStructuredMessage(ws, WSMessageType.DATA, singleton.lastFrame.metadata, singleton.lastFrame.data);
+          } else if (nextState == StreamingPhase.KEYFRAME && singleton.lastKeyframe) {
+            sendStructuredMessage(ws, WSMessageType.DATA, singleton.lastKeyframe.metadata, singleton.lastKeyframe.data);
+            nextState = StreamingPhase.RENDER;
+          }
           wsStreamingClients.set(id, { ...(currentClientData as WebsocketClient), state: nextState });
           break;
         default:

src/server/ws/scrcpy.ts

@@ -20,6 +20,7 @@ export interface DroidGroundFeatures {
   unlimitedTeams: boolean;
   fridaType: "full" | "jail";
   exploitAppDuration: number;
+  exploitAppMaxSize: number;
   ipAddress: string;
   logoLink: string | null;
 }
@@ -76,6 +77,11 @@ export interface WSMessage {
   data: Uint8Array;
 }
 
+export interface DroidGroundFrame {
+  metadata: WSMetadata;
+  data: Uint8Array;
+}
+
 export type WSCallback = (metadata: WSMetadata, binaryBuf: Uint8Array<ArrayBuffer>) => void;
 
 // ADB types