mcp-android-emulator 1.3.0 → 2.0.0

package/SECURITY.md

@@ -0,0 +1,43 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security issue in `mcp-android-emulator`, please report it
+privately to the maintainer via GitHub Security Advisories:
+
+<https://github.com/Anjos2/mcp-android-emulator/security/advisories/new>
+
+Please include:
+
+- A description of the issue and its impact.
+- Steps to reproduce, ideally without a weaponized payload.
+- Affected tool(s), file(s), and line number(s) if known.
+- Your preferred contact for follow-up.
+
+We aim to acknowledge reports within **72 hours** and publish a fix within
+**14 days** for critical issues when a remediation path is clear.
+
+## Scope
+
+The MCP server runs **with the privileges of the user that launched it**
+(typically your Claude Code / Claude Desktop process). A vulnerability in
+this package may allow code execution on the user's machine through any
+LLM that is authorised to call its tools. Please treat that blast radius
+when assessing severity.
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 2.x     | ✅         |
+| 1.x     | ❌ (superseded by 2.0.0; please upgrade) |
+
+## Disclosure Timeline
+
+We follow a coordinated disclosure model:
+
+1. Reporter submits advisory privately.
+2. Maintainer acknowledges, triages, and proposes a timeline.
+3. Fix is developed and tested on a private branch.
+4. A release is published, followed by the advisory going public.
+5. Reporter is credited unless they request otherwise.

package/dist/adb/runner.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Runner seguro para comandos adb.
+ *
+ * Finalidad:
+ *   Centraliza toda interacción con el binario adb usando execFile (NO exec),
+ *   lo que elimina la interpretación de metacaracteres shell en el HOST.
+ *   El host queda protegido aunque se pasen argumentos con ';', '|', '`', etc.
+ *
+ * Nota sobre adb shell:
+ *   Cuando se usa 'adb shell', adb concatena los argv con espacios y los
+ *   entrega al /system/bin/sh del device. El sh del device SÍ reinterpreta
+ *   metacaracteres. Por lo tanto, la defensa en profundidad exige que los
+ *   argumentos vengan validados (allowlist) por src/adb/validators.ts antes
+ *   de llegar aquí.
+ *
+ * Interrelación:
+ *   - Usado por src/index.ts (todas las tools migradas).
+ *   - Complementado por src/adb/validators.ts (allowlists zod).
+ *   - Config externa: variable de entorno ADB_PATH.
+ */
+export interface RunOptions {
+    /** Timeout en ms; default 30s. 0 o negativo = sin timeout. */
+    timeoutMs?: number;
+    /** Buffer máximo de stdout/stderr en bytes; default 10 MB. */
+    maxBufferBytes?: number;
+}
+/**
+ * Ejecuta `adb <args...>` sin pasar por shell del host.
+ * Cada elemento de args llega como argumento separado al binario adb.
+ */
+export declare function runAdb(args: string[], opts?: RunOptions): Promise<string>;
+/**
+ * Ejecuta `adb shell <argv...>`. Los tokens serán re-ensamblados por adb y
+ * pasados al sh del device. Los argumentos DEBEN estar validados contra
+ * shell metacharacters antes de invocar esta función (ver validators.ts).
+ */
+export declare function runAdbShell(argv: string[], opts?: RunOptions): Promise<string>;
+/**
+ * Ejecuta `adb exec-out <argv...>`. Útil para obtener bytes binarios sin
+ * transformación (screencap, pull de archivos). Los argumentos DEBEN estar
+ * validados. Devuelve un Buffer.
+ */
+export declare function runAdbExecOutBinary(argv: string[], opts?: RunOptions): Promise<Buffer>;

package/dist/adb/runner.js

@@ -0,0 +1,87 @@
+/**
+ * Runner seguro para comandos adb.
+ *
+ * Finalidad:
+ *   Centraliza toda interacción con el binario adb usando execFile (NO exec),
+ *   lo que elimina la interpretación de metacaracteres shell en el HOST.
+ *   El host queda protegido aunque se pasen argumentos con ';', '|', '`', etc.
+ *
+ * Nota sobre adb shell:
+ *   Cuando se usa 'adb shell', adb concatena los argv con espacios y los
+ *   entrega al /system/bin/sh del device. El sh del device SÍ reinterpreta
+ *   metacaracteres. Por lo tanto, la defensa en profundidad exige que los
+ *   argumentos vengan validados (allowlist) por src/adb/validators.ts antes
+ *   de llegar aquí.
+ *
+ * Interrelación:
+ *   - Usado por src/index.ts (todas las tools migradas).
+ *   - Complementado por src/adb/validators.ts (allowlists zod).
+ *   - Config externa: variable de entorno ADB_PATH.
+ */
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const ADB_PATH = process.env.ADB_PATH || "adb";
+const DEFAULT_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_BUFFER = 10 * 1024 * 1024;
+function normalizeOpts(opts) {
+    const t = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return {
+        timeout: t > 0 ? t : 0,
+        maxBuffer: opts.maxBufferBytes ?? DEFAULT_MAX_BUFFER,
+    };
+}
+/**
+ * Ejecuta `adb <args...>` sin pasar por shell del host.
+ * Cada elemento de args llega como argumento separado al binario adb.
+ */
+export async function runAdb(args, opts = {}) {
+    const { timeout, maxBuffer } = normalizeOpts(opts);
+    try {
+        const { stdout } = await execFileAsync(ADB_PATH, args, { timeout, maxBuffer });
+        return stdout.trim();
+    }
+    catch (error) {
+        throw wrapAdbError(error);
+    }
+}
+/**
+ * Ejecuta `adb shell <argv...>`. Los tokens serán re-ensamblados por adb y
+ * pasados al sh del device. Los argumentos DEBEN estar validados contra
+ * shell metacharacters antes de invocar esta función (ver validators.ts).
+ */
+export async function runAdbShell(argv, opts = {}) {
+    if (argv.length === 0) {
+        throw new Error("runAdbShell requires at least one argument");
+    }
+    return runAdb(["shell", ...argv], opts);
+}
+/**
+ * Ejecuta `adb exec-out <argv...>`. Útil para obtener bytes binarios sin
+ * transformación (screencap, pull de archivos). Los argumentos DEBEN estar
+ * validados. Devuelve un Buffer.
+ */
+export async function runAdbExecOutBinary(argv, opts = {}) {
+    if (argv.length === 0) {
+        throw new Error("runAdbExecOutBinary requires at least one argument");
+    }
+    const { timeout, maxBuffer } = normalizeOpts(opts);
+    return new Promise((resolve, reject) => {
+        execFile(ADB_PATH, ["exec-out", ...argv], { timeout, maxBuffer, encoding: "buffer" }, (error, stdout) => {
+            if (error) {
+                reject(wrapAdbError(error));
+                return;
+            }
+            resolve(stdout);
+        });
+    });
+}
+function wrapAdbError(error) {
+    if (error instanceof Error) {
+        // @ts-expect-error — stderr no es estándar pero lo añade child_process
+        const stderr = error.stderr;
+        const msg = stderr?.toString?.().trim() || error.message;
+        return new Error(`adb error: ${msg}`);
+    }
+    return new Error(`adb error: ${String(error)}`);
+}

package/dist/adb/validators.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Validators zod — allowlists estrictas para todo input que eventualmente
+ * llegará a `adb shell` (donde el sh del device reinterpreta metacaracteres).
+ *
+ * Finalidad:
+ *   Actuar como segunda línea de defensa sobre src/adb/runner.ts. El runner
+ *   protege el host (no invoca sh local); estos validators protegen el device
+ *   (bloquean metacaracteres antes de llegar al sh del device).
+ *
+ * Interrelación:
+ *   - Usado por los schemas de tool en src/index.ts.
+ *   - Combinable con z.object() normal de la librería zod.
+ */
+import { z } from "zod";
+/**
+ * Regex para metacaracteres shell peligrosos.
+ * Usado para rechazo en allowlists que admiten ciertos caracteres
+ * pero quieren excluir los más peligrosos explícitamente.
+ */
+export declare const SHELL_METACHARS: RegExp;
+export declare const packageNameSchema: z.ZodString;
+export declare const apkPathSchema: z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>;
+export declare const resourceIdSchema: z.ZodString;
+export declare const freeTextSchema: z.ZodEffects<z.ZodString, string, string>;
+export declare const typeableTextSchema: z.ZodEffects<z.ZodString, string, string>;
+export declare const searchFilterSchema: z.ZodEffects<z.ZodString, string, string>;
+export declare const positiveCountSchema: z.ZodNumber;
+export declare const coordinateSchema: z.ZodNumber;
+export declare const durationMsSchema: z.ZodNumber;

package/dist/adb/validators.js

@@ -0,0 +1,110 @@
+/**
+ * Validators zod — allowlists estrictas para todo input que eventualmente
+ * llegará a `adb shell` (donde el sh del device reinterpreta metacaracteres).
+ *
+ * Finalidad:
+ *   Actuar como segunda línea de defensa sobre src/adb/runner.ts. El runner
+ *   protege el host (no invoca sh local); estos validators protegen el device
+ *   (bloquean metacaracteres antes de llegar al sh del device).
+ *
+ * Interrelación:
+ *   - Usado por los schemas de tool en src/index.ts.
+ *   - Combinable con z.object() normal de la librería zod.
+ */
+import { z } from "zod";
+/**
+ * Regex para metacaracteres shell peligrosos.
+ * Usado para rechazo en allowlists que admiten ciertos caracteres
+ * pero quieren excluir los más peligrosos explícitamente.
+ */
+export const SHELL_METACHARS = /[;&|`$()<>\\"'\n\r\t\x00-\x1f]/;
+// ---------------------------------------------------------------------------
+// Android package name
+// Formato Java-compatible: segmentos separados por puntos, cada segmento
+// empieza con letra o underscore, continúa con alfanumérico/underscore.
+// Mínimo dos segmentos (no hay package top-level sin punto en Android real).
+// ---------------------------------------------------------------------------
+const PACKAGE_NAME_REGEX = /^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)+$/;
+export const packageNameSchema = z
+    .string()
+    .min(3)
+    .max(255)
+    .regex(PACKAGE_NAME_REGEX, "Invalid Android package name");
+// ---------------------------------------------------------------------------
+// APK path
+// Rechaza metacaracteres shell y exige extensión .apk.
+// La existencia del archivo se valida en el handler (no aquí, para que
+// los tests puedan usar paths simulados).
+// ---------------------------------------------------------------------------
+export const apkPathSchema = z
+    .string()
+    .min(5)
+    .max(4096)
+    .refine((p) => p.toLowerCase().endsWith(".apk"), {
+    message: "Must be a .apk file",
+})
+    .refine((p) => !SHELL_METACHARS.test(p), {
+    message: "Path contains disallowed characters",
+});
+// ---------------------------------------------------------------------------
+// Android resource-id (e.g. com.app:id/button_login)
+// ---------------------------------------------------------------------------
+const RESOURCE_ID_REGEX = /^[a-zA-Z_][a-zA-Z0-9_.]*:[a-zA-Z]+\/[a-zA-Z_][a-zA-Z0-9_]*$/;
+export const resourceIdSchema = z
+    .string()
+    .min(3)
+    .max(512)
+    .regex(RESOURCE_ID_REGEX, "Invalid Android resource-id");
+// ---------------------------------------------------------------------------
+// Texto libre del usuario (filter, search, assert)
+// Este texto NO llega al shell: se usa en JavaScript (String.includes,
+// RegExp.source con escape). Aceptamos caracteres amplios pero limitamos
+// longitud y prohibimos control characters para evitar sorpresas.
+// ---------------------------------------------------------------------------
+const CONTROL_CHARS = /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/;
+export const freeTextSchema = z
+    .string()
+    .max(1024)
+    .refine((s) => !CONTROL_CHARS.test(s), {
+    message: "Text contains control characters",
+});
+// ---------------------------------------------------------------------------
+// Texto que se va a tipear en un input Android (type_text, set_text).
+// Este texto PASA por el shell del device (`input text ...`). Usamos DENY-list
+// (rechazar solo metacaracteres shell y caracteres de control), NO allow-list,
+// para no romper i18n: acentos, ñ, CJK y emoji son válidos en inputs reales
+// de aplicaciones. Mismo nivel de seguridad que una allow-list ASCII porque
+// los shell metachars son el único vector de inyección.
+// ---------------------------------------------------------------------------
+export const typeableTextSchema = z
+    .string()
+    .min(0)
+    .max(2048)
+    .refine((s) => !SHELL_METACHARS.test(s), {
+    message: "Text contains shell metacharacters (; & | ` $ ( ) < > \\ \" ' or control chars). Use key events for these.",
+});
+// ---------------------------------------------------------------------------
+// Filter para list_packages / get_logs — usado en JS, no en shell.
+// ---------------------------------------------------------------------------
+export const searchFilterSchema = z
+    .string()
+    .max(256)
+    .refine((s) => !CONTROL_CHARS.test(s), {
+    message: "Filter contains control characters",
+});
+// ---------------------------------------------------------------------------
+// Conteo numérico sanitizado (lines en get_logs, etc).
+// ---------------------------------------------------------------------------
+export const positiveCountSchema = z
+    .number()
+    .int()
+    .positive()
+    .max(100_000);
+// ---------------------------------------------------------------------------
+// Coordenadas (seguras por tipo, pero clamp a límites razonables).
+// ---------------------------------------------------------------------------
+export const coordinateSchema = z.number().int().min(0).max(100_000);
+// ---------------------------------------------------------------------------
+// Duración en ms.
+// ---------------------------------------------------------------------------
+export const durationMsSchema = z.number().int().nonnegative().max(600_000);

package/dist/index.d.ts

@@ -1,7 +1,22 @@
 #!/usr/bin/env node
 /**
- * MCP Server for Android Emulator
- * Enables AI assistants to interact with Android devices/emulators via ADB
+ * MCP Server for Android Emulator.
+ *
+ * Finalidad:
+ *   Expone 43 tools MCP que permiten a un asistente LLM controlar un device
+ *   Android vía ADB (screenshot, tap, type, launch apps, logs, asserts...).
+ *
+ * Interrelación:
+ *   - src/adb/runner.ts    → ejecución segura de adb (execFile, sin shell del host).
+ *   - src/adb/validators.ts → allowlists zod para inputs que llegan al sh del device.
+ *   - test/                 → smoke tests que validan que payloads shell-metachar son
+ *                             rechazados por los validators y que los argv construidos
+ *                             son los esperados.
+ *
+ * Seguridad:
+ *   Fix de la issue #1 (command injection). TODOS los argumentos derivados del
+ *   LLM pasan por zod.refine antes de llegar al runner, y el runner usa execFile
+ *   (no exec), por lo que /bin/sh del host nunca reinterpreta la línea de comando.
  *
  * @license MIT
  */