mcp-maestro-mobile-ai 1.3.1 → 1.6.0

package/src/mcp-server/utils/security.js

@@ -0,0 +1,1200 @@
+/**
+ * Security Utility Module
+ *
+ * Implements security boundaries for the MCP Maestro Mobile AI server.
+ * Includes Safe Mode, command allowlists, blocked operations, and input validation.
+ *
+ * @module security
+ * @version 1.0.0
+ */
+
+import { logger } from "./logger.js";
+
+// ============================================
+// CONSTANTS & CONFIGURATION
+// ============================================
+
+/**
+ * Security modes available
+ */
+export const SecurityMode = {
+  SAFE: "safe",
+  FULL: "full",
+};
+
+/**
+ * Security error codes
+ */
+export const SecurityErrorCode = {
+  SAFE_MODE_VIOLATION: "SAFE_MODE_VIOLATION",
+  BLOCKED_COMMAND: "BLOCKED_COMMAND",
+  BLOCKED_PATTERN: "BLOCKED_PATTERN",
+  INVALID_INPUT: "INVALID_INPUT",
+  UNAUTHORIZED_OPERATION: "UNAUTHORIZED_OPERATION",
+};
+
+// ============================================
+// SECURITY ERROR CLASS
+// ============================================
+
+/**
+ * Custom error class for security violations
+ */
+export class SecurityError extends Error {
+  /**
+   * Create a SecurityError
+   * @param {string} message - Error message
+   * @param {string} code - Error code from SecurityErrorCode
+   * @param {object} details - Additional details about the error
+   */
+  constructor(
+    message,
+    code = SecurityErrorCode.UNAUTHORIZED_OPERATION,
+    details = {}
+  ) {
+    super(message);
+    this.name = "SecurityError";
+    this.code = code;
+    this.details = details;
+    this.timestamp = new Date().toISOString();
+
+    // Log security event
+    logger.warn(`Security violation: ${code}`, {
+      message,
+      code,
+      details,
+      timestamp: this.timestamp,
+    });
+  }
+
+  /**
+   * Convert error to JSON for API responses
+   */
+  toJSON() {
+    return {
+      error: this.name,
+      message: this.message,
+      code: this.code,
+      details: this.details,
+      timestamp: this.timestamp,
+    };
+  }
+}
+
+// ============================================
+// SAFE MODE FUNCTIONS
+// ============================================
+
+/**
+ * Check if Safe Mode is enabled
+ * Safe Mode is ON by default for security
+ *
+ * @returns {boolean} True if Safe Mode is enabled
+ */
+export function isSafeModeEnabled() {
+  const safeMode = process.env.SAFE_MODE;
+
+  // Safe Mode is ON by default (secure by default)
+  // Only disable if explicitly set to 'false'
+  if (safeMode === "false" || safeMode === "0") {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Get the current security mode
+ *
+ * @returns {string} Current security mode ('safe' or 'full')
+ */
+export function getSecurityMode() {
+  return isSafeModeEnabled() ? SecurityMode.SAFE : SecurityMode.FULL;
+}
+
+/**
+ * Get security configuration summary
+ *
+ * @returns {object} Security configuration details
+ */
+export function getSecurityConfig() {
+  return {
+    safeMode: isSafeModeEnabled(),
+    mode: getSecurityMode(),
+    logSecurityEvents: process.env.LOG_SECURITY_EVENTS !== "false",
+  };
+}
+
+// ============================================
+// INPUT SANITIZATION
+// ============================================
+
+/**
+ * Sanitize a string input by removing dangerous characters
+ *
+ * @param {string} input - Input string to sanitize
+ * @returns {string} Sanitized string
+ */
+export function sanitizeInput(input) {
+  if (typeof input !== "string") {
+    return input;
+  }
+
+  // Remove null bytes
+  let sanitized = input.replace(/\0/g, "");
+
+  // Remove control characters (except newlines and tabs)
+  // Using character code range to avoid linter issues with control chars
+  sanitized = sanitized
+    .split("")
+    .filter((char) => {
+      const code = char.charCodeAt(0);
+      // Allow printable ASCII, newlines (\n = 10), carriage return (\r = 13), and tabs (\t = 9)
+      return (
+        code === 9 ||
+        code === 10 ||
+        code === 13 ||
+        (code >= 32 && code <= 126) ||
+        code > 127
+      );
+    })
+    .join("");
+
+  return sanitized;
+}
+
+/**
+ * Sanitize a file path
+ *
+ * @param {string} filePath - File path to sanitize
+ * @returns {string} Sanitized file path
+ * @throws {SecurityError} If path contains dangerous patterns
+ */
+export function sanitizeFilePath(filePath) {
+  if (typeof filePath !== "string") {
+    throw new SecurityError(
+      "File path must be a string",
+      SecurityErrorCode.INVALID_INPUT,
+      { received: typeof filePath }
+    );
+  }
+
+  // Normalize path separators
+  let sanitized = filePath.replace(/\\/g, "/");
+
+  // Remove null bytes
+  sanitized = sanitized.replace(/\0/g, "");
+
+  // Check for path traversal attempts
+  if (sanitized.includes("..")) {
+    throw new SecurityError(
+      "Path traversal not allowed",
+      SecurityErrorCode.BLOCKED_PATTERN,
+      { path: filePath, pattern: ".." }
+    );
+  }
+
+  return sanitized;
+}
+
+/**
+ * Validate that an app ID is properly formatted
+ *
+ * @param {string} appId - App package ID to validate
+ * @returns {boolean} True if valid
+ * @throws {SecurityError} If app ID is invalid
+ */
+export function validateAppId(appId) {
+  if (typeof appId !== "string" || appId.length === 0) {
+    throw new SecurityError(
+      "App ID must be a non-empty string",
+      SecurityErrorCode.INVALID_INPUT,
+      { received: appId }
+    );
+  }
+
+  // Valid app ID pattern: lowercase letters, numbers, dots, underscores
+  // Examples: com.google.android.youtube, com.example.app
+  const appIdPattern = /^[a-zA-Z][a-zA-Z0-9_]*(\.[a-zA-Z][a-zA-Z0-9_]*)+$/;
+
+  if (!appIdPattern.test(appId)) {
+    throw new SecurityError(
+      "Invalid app ID format",
+      SecurityErrorCode.INVALID_INPUT,
+      { appId, expectedPattern: "com.example.app" }
+    );
+  }
+
+  return true;
+}
+
+/**
+ * Validate a device ID format
+ *
+ * @param {string} deviceId - Device ID to validate
+ * @returns {boolean} True if valid
+ * @throws {SecurityError} If device ID is invalid
+ */
+export function validateDeviceId(deviceId) {
+  if (typeof deviceId !== "string" || deviceId.length === 0) {
+    throw new SecurityError(
+      "Device ID must be a non-empty string",
+      SecurityErrorCode.INVALID_INPUT,
+      { received: deviceId }
+    );
+  }
+
+  // Valid device ID patterns:
+  // - emulator-5554 (emulator)
+  // - RF8M12345XY (physical device)
+  // - 192.168.1.100:5555 (network device)
+  const deviceIdPattern = /^[a-zA-Z0-9][a-zA-Z0-9_\-.:]*$/;
+
+  if (!deviceIdPattern.test(deviceId)) {
+    throw new SecurityError(
+      "Invalid device ID format",
+      SecurityErrorCode.INVALID_INPUT,
+      { deviceId }
+    );
+  }
+
+  // Check for maximum length
+  if (deviceId.length > 100) {
+    throw new SecurityError(
+      "Device ID too long",
+      SecurityErrorCode.INVALID_INPUT,
+      { deviceId, maxLength: 100 }
+    );
+  }
+
+  return true;
+}
+
+// ============================================
+// OPERATION PERMISSION CHECKS
+// ============================================
+
+/**
+ * Operation types for permission checking
+ */
+export const OperationType = {
+  // Read-only operations (always allowed)
+  READ: "read",
+  LIST: "list",
+  VALIDATE: "validate",
+
+  // Test operations (allowed in all modes)
+  RUN_TEST: "run_test",
+  SCREENSHOT: "screenshot",
+
+  // Potentially destructive operations (blocked in Safe Mode)
+  INSTALL_APP: "install_app",
+  UNINSTALL_APP: "uninstall_app",
+  CLEAR_APP_DATA: "clear_app_data",
+
+  // Always blocked operations
+  SYSTEM_SETTINGS: "system_settings",
+  FILE_SYSTEM: "file_system",
+  DEVICE_ADMIN: "device_admin",
+};
+
+/**
+ * Operations allowed in Safe Mode
+ */
+const SAFE_MODE_ALLOWED_OPERATIONS = new Set([
+  OperationType.READ,
+  OperationType.LIST,
+  OperationType.VALIDATE,
+  OperationType.RUN_TEST,
+  OperationType.SCREENSHOT,
+]);
+
+/**
+ * Operations allowed in Full Mode (Safe Mode + these)
+ */
+const FULL_MODE_ADDITIONAL_OPERATIONS = new Set([
+  OperationType.INSTALL_APP,
+  OperationType.UNINSTALL_APP,
+  OperationType.CLEAR_APP_DATA,
+]);
+
+/**
+ * Operations that are always blocked regardless of mode
+ */
+const ALWAYS_BLOCKED_OPERATIONS = new Set([
+  OperationType.SYSTEM_SETTINGS,
+  OperationType.FILE_SYSTEM,
+  OperationType.DEVICE_ADMIN,
+]);
+
+/**
+ * Check if an operation is allowed based on current security mode
+ *
+ * @param {string} operation - Operation type from OperationType
+ * @returns {boolean} True if operation is allowed
+ */
+export function isOperationAllowed(operation) {
+  // Always blocked operations
+  if (ALWAYS_BLOCKED_OPERATIONS.has(operation)) {
+    logger.warn(`Blocked operation attempted: ${operation}`);
+    return false;
+  }
+
+  // Check Safe Mode operations
+  if (SAFE_MODE_ALLOWED_OPERATIONS.has(operation)) {
+    return true;
+  }
+
+  // If not in Safe Mode, check additional operations
+  if (!isSafeModeEnabled() && FULL_MODE_ADDITIONAL_OPERATIONS.has(operation)) {
+    return true;
+  }
+
+  // Unknown operation - deny by default
+  logger.warn(`Unknown operation denied: ${operation}`);
+  return false;
+}
+
+/**
+ * Assert that an operation is allowed, throw if not
+ *
+ * @param {string} operation - Operation type from OperationType
+ * @param {string} description - Description for error message
+ * @throws {SecurityError} If operation is not allowed
+ */
+export function assertOperationAllowed(operation, description = "") {
+  if (!isOperationAllowed(operation)) {
+    const mode = getSecurityMode();
+    const isBlocked = ALWAYS_BLOCKED_OPERATIONS.has(operation);
+
+    throw new SecurityError(
+      isBlocked
+        ? `Operation "${operation}" is not allowed: ${description}`
+        : `Operation "${operation}" is not allowed in Safe Mode: ${description}`,
+      isBlocked
+        ? SecurityErrorCode.BLOCKED_COMMAND
+        : SecurityErrorCode.SAFE_MODE_VIOLATION,
+      { operation, mode, description }
+    );
+  }
+}
+
+// ============================================
+// COMMAND ALLOWLISTS
+// ============================================
+
+/**
+ * Allowed Maestro CLI commands
+ * Only these commands can be executed via the MCP server
+ */
+export const MAESTRO_ALLOWED_COMMANDS = new Set([
+  "test", // Run test flow
+  "validate", // Validate YAML
+  "screenshot", // Capture screen
+  "--version", // Version check
+  "--help", // Help
+  "hierarchy", // View hierarchy (useful for debugging)
+]);
+
+/**
+ * Allowed Maestro command flags
+ */
+export const MAESTRO_ALLOWED_FLAGS = new Set([
+  "--device", // Device selection
+  "--format", // Output format
+  "--output", // Output path
+  "--no-ansi", // Disable ANSI colors
+  "--debug", // Debug mode
+  "-e", // Environment variable
+  "--env", // Environment variable
+]);
+
+/**
+ * ADB commands allowed in Safe Mode
+ * These are read-only and non-destructive operations
+ */
+export const ADB_SAFE_MODE_COMMANDS = new Set([
+  "devices", // List devices
+  "devices -l", // List devices with details
+  "get-state", // Get device state
+  "get-serialno", // Get serial number
+  "shell getprop", // Get device properties
+  "shell pm list packages", // List installed packages
+  "shell pm path", // Get APK path
+  "shell dumpsys package", // Package info
+  "shell input tap", // Tap gesture
+  "shell input text", // Text input
+  "shell input swipe", // Swipe gesture
+  "shell input keyevent", // Key event
+  "shell screencap", // Screenshot
+  "pull", // Pull file from device
+  "version", // ADB version
+]);
+
+/**
+ * Additional ADB commands allowed in Full Mode
+ * These are potentially destructive operations
+ */
+export const ADB_FULL_MODE_COMMANDS = new Set([
+  "install", // Install APK
+  "install-multiple", // Install split APKs
+  "uninstall", // Uninstall app
+  "shell pm clear", // Clear app data
+  "shell am force-stop", // Force stop app
+  "shell am start", // Start activity
+  "shell am broadcast", // Send broadcast
+  "push", // Push file to device
+  "logcat", // View logs
+  "bugreport", // Bug report
+]);
+
+/**
+ * ADB commands that are ALWAYS blocked regardless of mode
+ * These are dangerous system-level operations
+ */
+export const ADB_BLOCKED_COMMANDS = new Set([
+  "root", // Root access
+  "unroot", // Unroot
+  "reboot", // Reboot device
+  "reboot-bootloader", // Reboot to bootloader
+  "reboot recovery", // Reboot to recovery
+  "shell rm", // Delete files
+  "shell rm -rf", // Recursive delete
+  "shell rm -r", // Recursive delete
+  "shell rmdir", // Remove directory
+  "shell mv", // Move files
+  "shell cp", // Copy files (can overwrite)
+  "shell dd", // Direct disk access
+  "shell su", // Superuser
+  "shell settings put", // Change settings
+  "shell settings delete", // Delete settings
+  "shell pm disable", // Disable package
+  "shell pm enable", // Enable package (can be dangerous)
+  "shell pm grant", // Grant permissions
+  "shell pm revoke", // Revoke permissions
+  "shell pm set-installer", // Set installer
+  "shell pm hide", // Hide package
+  "shell pm unhide", // Unhide package
+  "shell wm", // Window manager (screen changes)
+  "shell svc", // Service control
+  "shell setprop", // Set system properties
+  "shell am kill", // Kill process
+  "shell am kill-all", // Kill all processes
+  "shell am crash", // Crash app
+  "remount", // Remount filesystem
+  "disable-verity", // Disable verification
+  "enable-verity", // Enable verification
+  "keygen", // Key generation
+  "restore", // Restore backup
+  "sideload", // Sideload OTA
+  "shell content delete", // Delete content
+  "shell content update", // Update content
+  "emu kill", // Kill emulator
+  "emu avd stop", // Stop AVD
+]);
+
+/**
+ * Check if a Maestro command is allowed
+ *
+ * @param {string} command - The Maestro command to check
+ * @returns {object} Result with allowed status and reason
+ */
+export function isMaestroCommandAllowed(command) {
+  if (typeof command !== "string" || command.length === 0) {
+    return {
+      allowed: false,
+      reason: "Command must be a non-empty string",
+    };
+  }
+
+  // Extract the base command (first argument)
+  const parts = command.trim().split(/\s+/);
+  const baseCommand = parts[0];
+
+  // Check if base command is allowed
+  if (!MAESTRO_ALLOWED_COMMANDS.has(baseCommand)) {
+    logSecurityEvent("MAESTRO_COMMAND_BLOCKED", {
+      command,
+      baseCommand,
+      reason: "Command not in allowlist",
+    });
+
+    return {
+      allowed: false,
+      reason: `Maestro command "${baseCommand}" is not allowed`,
+      allowedCommands: Array.from(MAESTRO_ALLOWED_COMMANDS),
+    };
+  }
+
+  // Validate flags if present
+  for (let i = 1; i < parts.length; i++) {
+    const part = parts[i];
+    // Check if it's a flag (starts with -)
+    if (part.startsWith("-")) {
+      // Extract flag name (handle --flag=value format)
+      const flagName = part.split("=")[0];
+
+      if (!MAESTRO_ALLOWED_FLAGS.has(flagName) && flagName !== "--device") {
+        // Allow unknown flags but log them
+        logger.info(`Unknown Maestro flag used: ${flagName}`);
+      }
+    }
+  }
+
+  return {
+    allowed: true,
+    command: baseCommand,
+  };
+}
+
+/**
+ * Check if an ADB command is allowed based on current security mode
+ *
+ * @param {string} command - The ADB command to check
+ * @returns {object} Result with allowed status and reason
+ */
+export function isAdbCommandAllowed(command) {
+  if (typeof command !== "string" || command.length === 0) {
+    return {
+      allowed: false,
+      reason: "Command must be a non-empty string",
+    };
+  }
+
+  const trimmedCommand = command.trim();
+  const safeMode = isSafeModeEnabled();
+
+  // Check against blocked commands first (always blocked)
+  for (const blocked of ADB_BLOCKED_COMMANDS) {
+    if (
+      trimmedCommand === blocked ||
+      trimmedCommand.startsWith(blocked + " ")
+    ) {
+      logSecurityEvent("ADB_COMMAND_BLOCKED", {
+        command: trimmedCommand,
+        blockedPattern: blocked,
+        reason: "Command is in blocked list",
+      });
+
+      return {
+        allowed: false,
+        reason: `ADB command "${blocked}" is blocked for security reasons`,
+        blocked: true,
+      };
+    }
+  }
+
+  // Check against Safe Mode allowlist
+  for (const allowed of ADB_SAFE_MODE_COMMANDS) {
+    if (
+      trimmedCommand === allowed ||
+      trimmedCommand.startsWith(allowed + " ")
+    ) {
+      return {
+        allowed: true,
+        mode: "safe",
+      };
+    }
+  }
+
+  // If not in Safe Mode, check Full Mode commands
+  if (!safeMode) {
+    for (const allowed of ADB_FULL_MODE_COMMANDS) {
+      if (
+        trimmedCommand === allowed ||
+        trimmedCommand.startsWith(allowed + " ")
+      ) {
+        return {
+          allowed: true,
+          mode: "full",
+        };
+      }
+    }
+  }
+
+  // Check if it's a Full Mode command that's blocked by Safe Mode
+  for (const fullModeCmd of ADB_FULL_MODE_COMMANDS) {
+    if (
+      trimmedCommand === fullModeCmd ||
+      trimmedCommand.startsWith(fullModeCmd + " ")
+    ) {
+      logSecurityEvent("ADB_COMMAND_SAFE_MODE_BLOCKED", {
+        command: trimmedCommand,
+        reason: "Command requires Full Mode",
+      });
+
+      return {
+        allowed: false,
+        reason: `ADB command "${fullModeCmd}" is not allowed in Safe Mode. Set SAFE_MODE=false to enable.`,
+        requiresFullMode: true,
+      };
+    }
+  }
+
+  // Unknown command - deny by default
+  logSecurityEvent("ADB_COMMAND_UNKNOWN", {
+    command: trimmedCommand,
+    reason: "Command not recognized",
+  });
+
+  return {
+    allowed: false,
+    reason: `ADB command not recognized or not allowed: "${trimmedCommand}"`,
+  };
+}
+
+/**
+ * Validate a complete command before execution
+ *
+ * @param {string} command - The command to validate
+ * @param {string} type - Command type: 'maestro' or 'adb'
+ * @returns {object} Validation result
+ * @throws {SecurityError} If command is not allowed
+ */
+export function validateCommand(command, type) {
+  let result;
+
+  if (type === "maestro") {
+    result = isMaestroCommandAllowed(command);
+  } else if (type === "adb") {
+    result = isAdbCommandAllowed(command);
+  } else {
+    throw new SecurityError(
+      `Unknown command type: ${type}`,
+      SecurityErrorCode.INVALID_INPUT,
+      { type, allowedTypes: ["maestro", "adb"] }
+    );
+  }
+
+  if (!result.allowed) {
+    throw new SecurityError(
+      result.reason,
+      result.blocked
+        ? SecurityErrorCode.BLOCKED_COMMAND
+        : SecurityErrorCode.SAFE_MODE_VIOLATION,
+      { command, type, ...result }
+    );
+  }
+
+  return result;
+}
+
+/**
+ * Get all allowed commands for display/documentation
+ *
+ * @returns {object} Object containing all allowlists
+ */
+export function getAllowedCommands() {
+  return {
+    maestro: {
+      commands: Array.from(MAESTRO_ALLOWED_COMMANDS),
+      flags: Array.from(MAESTRO_ALLOWED_FLAGS),
+    },
+    adb: {
+      safeMode: Array.from(ADB_SAFE_MODE_COMMANDS),
+      fullMode: Array.from(ADB_FULL_MODE_COMMANDS),
+      blocked: Array.from(ADB_BLOCKED_COMMANDS),
+    },
+  };
+}
+
+// ============================================
+// BLOCKED PATTERNS & DETECTION
+// ============================================
+
+/**
+ * Pattern types for categorizing blocked patterns
+ */
+export const PatternType = {
+  SHELL_INJECTION: "shell_injection",
+  COMMAND_SUBSTITUTION: "command_substitution",
+  PATH_TRAVERSAL: "path_traversal",
+  ENVIRONMENT_EXPANSION: "environment_expansion",
+  NULL_BYTE: "null_byte",
+  DANGEROUS_CHARACTERS: "dangerous_characters",
+  SQL_INJECTION: "sql_injection",
+  SCRIPT_INJECTION: "script_injection",
+};
+
+/**
+ * Blocked patterns with descriptions
+ * Each pattern has a regex, type, and description for better error messages
+ */
+export const BLOCKED_PATTERNS = [
+  // Shell injection patterns
+  {
+    pattern: /[;&|]/,
+    type: PatternType.SHELL_INJECTION,
+    description: "Shell command chaining characters (; & |)",
+    example: "command1; command2",
+  },
+  {
+    pattern: /\|\|/,
+    type: PatternType.SHELL_INJECTION,
+    description: "Shell OR operator (||)",
+    example: "cmd1 || cmd2",
+  },
+  {
+    pattern: /&&/,
+    type: PatternType.SHELL_INJECTION,
+    description: "Shell AND operator (&&)",
+    example: "cmd1 && cmd2",
+  },
+
+  // Command substitution patterns
+  {
+    pattern: /`[^`]*`/,
+    type: PatternType.COMMAND_SUBSTITUTION,
+    description: "Backtick command substitution",
+    example: "`whoami`",
+  },
+  {
+    pattern: /\$\([^)]*\)/,
+    type: PatternType.COMMAND_SUBSTITUTION,
+    description: "Dollar-paren command substitution",
+    example: "$(whoami)",
+  },
+
+  // Path traversal patterns
+  {
+    pattern: /\.\.[/\\]/,
+    type: PatternType.PATH_TRAVERSAL,
+    description: "Parent directory traversal (../)",
+    example: "../../../etc/passwd",
+  },
+  {
+    pattern: /[/\\]\.\./,
+    type: PatternType.PATH_TRAVERSAL,
+    description: "Parent directory traversal (/..)",
+    example: "/dir/../secret",
+  },
+
+  // Environment variable expansion
+  {
+    pattern: /\$\{[^}]+\}/,
+    type: PatternType.ENVIRONMENT_EXPANSION,
+    description: "Environment variable expansion (${VAR})",
+    example: "${HOME}",
+  },
+  {
+    pattern: /\$[A-Z_][A-Z0-9_]*/i,
+    type: PatternType.ENVIRONMENT_EXPANSION,
+    description: "Environment variable reference ($VAR)",
+    example: "$PATH",
+  },
+
+  // Null byte injection - using Unicode escape for linter compatibility
+  {
+    pattern: new RegExp(String.fromCharCode(0)),
+    type: PatternType.NULL_BYTE,
+    description: "Null byte injection",
+    example: "file.txt\\0.jpg",
+  },
+  {
+    pattern: /%00/,
+    type: PatternType.NULL_BYTE,
+    description: "URL-encoded null byte",
+    example: "file.txt%00.jpg",
+  },
+
+  // Dangerous shell characters
+  {
+    pattern: /[><]/,
+    type: PatternType.DANGEROUS_CHARACTERS,
+    description: "Shell redirection characters (< >)",
+    example: "cmd > /etc/passwd",
+  },
+  {
+    pattern: /\n|\r/,
+    type: PatternType.DANGEROUS_CHARACTERS,
+    description: "Newline characters (potential command injection)",
+    example: "cmd\\nmalicious",
+  },
+
+  // Script injection (for YAML context)
+  {
+    pattern: /<script[^>]*>/i,
+    type: PatternType.SCRIPT_INJECTION,
+    description: "Script tag injection",
+    example: "<script>alert(1)</script>",
+  },
+  {
+    pattern: /javascript:/i,
+    type: PatternType.SCRIPT_INJECTION,
+    description: "JavaScript protocol",
+    example: "javascript:alert(1)",
+  },
+];
+
+/**
+ * Patterns that are only blocked in certain contexts
+ */
+export const CONTEXT_SENSITIVE_PATTERNS = {
+  // Blocked only in shell commands
+  shellCommand: [
+    {
+      pattern: /\$/,
+      type: PatternType.ENVIRONMENT_EXPANSION,
+      description: "Dollar sign in shell context",
+    },
+    {
+      pattern: /!/,
+      type: PatternType.SHELL_INJECTION,
+      description: "History expansion character",
+    },
+  ],
+
+  // Blocked only in file paths
+  filePath: [
+    {
+      pattern: /:/,
+      type: PatternType.DANGEROUS_CHARACTERS,
+      description: "Colon in file path (Windows drive or ADS)",
+    },
+    {
+      pattern: /\*/,
+      type: PatternType.DANGEROUS_CHARACTERS,
+      description: "Wildcard in file path",
+    },
+    {
+      pattern: /\?/,
+      type: PatternType.DANGEROUS_CHARACTERS,
+      description: "Wildcard in file path",
+    },
+  ],
+
+  // Blocked only in app IDs
+  appId: [
+    {
+      pattern: /[^a-zA-Z0-9_.]/,
+      type: PatternType.DANGEROUS_CHARACTERS,
+      description: "Invalid character in app ID",
+    },
+  ],
+};
+
+/**
+ * Check if input contains any blocked patterns
+ *
+ * @param {string} input - Input string to check
+ * @param {string} context - Optional context for context-sensitive checks
+ * @returns {object} Result with detected status and pattern info
+ */
+export function containsBlockedPattern(input, context = null) {
+  if (typeof input !== "string") {
+    return {
+      detected: false,
+      reason: "Input is not a string",
+    };
+  }
+
+  // Check global blocked patterns
+  for (const patternInfo of BLOCKED_PATTERNS) {
+    if (patternInfo.pattern.test(input)) {
+      logSecurityEvent("BLOCKED_PATTERN_DETECTED", {
+        input: input.substring(0, 100), // Truncate for logging
+        patternType: patternInfo.type,
+        description: patternInfo.description,
+        context,
+      });
+
+      return {
+        detected: true,
+        type: patternInfo.type,
+        description: patternInfo.description,
+        example: patternInfo.example,
+        pattern: patternInfo.pattern.toString(),
+      };
+    }
+  }
+
+  // Check context-sensitive patterns if context is provided
+  if (context && CONTEXT_SENSITIVE_PATTERNS[context]) {
+    for (const patternInfo of CONTEXT_SENSITIVE_PATTERNS[context]) {
+      if (patternInfo.pattern.test(input)) {
+        logSecurityEvent("CONTEXT_PATTERN_DETECTED", {
+          input: input.substring(0, 100),
+          patternType: patternInfo.type,
+          description: patternInfo.description,
+          context,
+        });
+
+        return {
+          detected: true,
+          type: patternInfo.type,
+          description: patternInfo.description,
+          context,
+          pattern: patternInfo.pattern.toString(),
+        };
+      }
+    }
+  }
+
+  return {
+    detected: false,
+  };
+}
+
+/**
+ * Assert that input does not contain blocked patterns
+ *
+ * @param {string} input - Input string to check
+ * @param {string} inputName - Name of the input for error messages
+ * @param {string} context - Optional context for context-sensitive checks
+ * @throws {SecurityError} If blocked pattern is detected
+ */
+export function assertNoBlockedPatterns(
+  input,
+  inputName = "input",
+  context = null
+) {
+  const result = containsBlockedPattern(input, context);
+
+  if (result.detected) {
+    throw new SecurityError(
+      `Blocked pattern detected in ${inputName}: ${result.description}`,
+      SecurityErrorCode.BLOCKED_PATTERN,
+      {
+        inputName,
+        patternType: result.type,
+        description: result.description,
+        context,
+      }
+    );
+  }
+}
+
+/**
+ * Sanitize input by removing or escaping blocked patterns
+ * Use with caution - validation is preferred over sanitization
+ *
+ * @param {string} input - Input string to sanitize
+ * @param {object} options - Sanitization options
+ * @returns {string} Sanitized string
+ */
+export function sanitizeBlockedPatterns(input, options = {}) {
+  if (typeof input !== "string") {
+    return input;
+  }
+
+  let sanitized = input;
+
+  // Remove null bytes - using character code for linter compatibility
+  const nullByteRegex = new RegExp(String.fromCharCode(0), "g");
+  sanitized = sanitized.replace(nullByteRegex, "");
+  sanitized = sanitized.replace(/%00/g, "");
+
+  // Remove shell injection characters
+  if (options.removeShellChars !== false) {
+    sanitized = sanitized.replace(/[;&|`]/g, "");
+  }
+
+  // Remove path traversal
+  if (options.removePathTraversal !== false) {
+    sanitized = sanitized.replace(/\.\./g, "");
+  }
+
+  // Remove environment expansion (but keep $ for normal text)
+  if (options.removeEnvExpansion) {
+    sanitized = sanitized.replace(/\$\{[^}]+\}/g, "");
+    sanitized = sanitized.replace(/\$\([^)]*\)/g, "");
+  }
+
+  // Remove control characters
+  if (options.removeControlChars !== false) {
+    sanitized = sanitized.replace(/[\n\r]/g, " ");
+  }
+
+  return sanitized;
+}
+
+/**
+ * Validate and sanitize a complete command before execution
+ * This combines pattern detection with command allowlist checking
+ *
+ * @param {string} command - Command to validate
+ * @param {string} type - Command type ('maestro' or 'adb')
+ * @returns {object} Validation result with sanitized command
+ * @throws {SecurityError} If validation fails
+ */
+export function validateAndSanitizeCommand(command, type) {
+  // First check for blocked patterns
+  assertNoBlockedPatterns(command, `${type} command`, "shellCommand");
+
+  // Then validate against allowlists
+  const allowlistResult = validateCommand(command, type);
+
+  return {
+    valid: true,
+    command: sanitizeInput(command),
+    type,
+    ...allowlistResult,
+  };
+}
+
+/**
+ * Check if YAML content contains potentially dangerous patterns
+ *
+ * @param {string} yamlContent - YAML content to check
+ * @returns {object} Result with detected issues
+ */
+export function checkYamlSecurity(yamlContent) {
+  if (typeof yamlContent !== "string") {
+    return {
+      safe: false,
+      issues: ["YAML content must be a string"],
+    };
+  }
+
+  const issues = [];
+  const warnings = [];
+
+  // Check for blocked patterns (excluding some that are valid in YAML)
+  const nullBytePattern = new RegExp(String.fromCharCode(0));
+  const dangerousPatterns = [
+    { pattern: /\$\([^)]*\)/, message: "Command substitution $()" },
+    { pattern: /`[^`]*`/, message: "Backtick command substitution" },
+    { pattern: /<script/i, message: "Script tag" },
+    { pattern: /javascript:/i, message: "JavaScript protocol" },
+    { pattern: nullBytePattern, message: "Null byte" },
+  ];
+
+  for (const { pattern, message } of dangerousPatterns) {
+    if (pattern.test(yamlContent)) {
+      issues.push(`Dangerous pattern detected: ${message}`);
+    }
+  }
+
+  // Check for suspicious YAML constructs
+  if (yamlContent.includes("!!python")) {
+    issues.push("Python tag detected - potential code execution");
+  }
+
+  if (yamlContent.includes("!!ruby")) {
+    issues.push("Ruby tag detected - potential code execution");
+  }
+
+  // Warnings (not blocking but suspicious)
+  if (yamlContent.includes("shell:") || yamlContent.includes("exec:")) {
+    warnings.push("Shell/exec command found - review carefully");
+  }
+
+  if (issues.length > 0) {
+    logSecurityEvent("YAML_SECURITY_ISSUES", {
+      issueCount: issues.length,
+      issues,
+    });
+  }
+
+  return {
+    safe: issues.length === 0,
+    issues,
+    warnings,
+  };
+}
+
+/**
+ * Get all blocked patterns for documentation
+ *
+ * @returns {object} All blocked patterns organized by type
+ */
+export function getBlockedPatterns() {
+  const organized = {};
+
+  for (const patternInfo of BLOCKED_PATTERNS) {
+    if (!organized[patternInfo.type]) {
+      organized[patternInfo.type] = [];
+    }
+    organized[patternInfo.type].push({
+      description: patternInfo.description,
+      example: patternInfo.example,
+    });
+  }
+
+  return {
+    patterns: organized,
+    contextSensitive: Object.keys(CONTEXT_SENSITIVE_PATTERNS),
+    patternTypes: Object.values(PatternType),
+  };
+}
+
+// ============================================
+// SECURITY EVENT LOGGING
+// ============================================
+
+/**
+ * Log a security event
+ *
+ * @param {string} event - Event type
+ * @param {object} details - Event details
+ */
+export function logSecurityEvent(event, details = {}) {
+  if (process.env.LOG_SECURITY_EVENTS === "false") {
+    return;
+  }
+
+  logger.info(`[SECURITY] ${event}`, {
+    event,
+    ...details,
+    timestamp: new Date().toISOString(),
+    safeMode: isSafeModeEnabled(),
+  });
+}
+
+// ============================================
+// EXPORTS
+// ============================================
+
+export default {
+  // Constants
+  SecurityMode,
+  SecurityErrorCode,
+  OperationType,
+  PatternType,
+
+  // Command Allowlists
+  MAESTRO_ALLOWED_COMMANDS,
+  MAESTRO_ALLOWED_FLAGS,
+  ADB_SAFE_MODE_COMMANDS,
+  ADB_FULL_MODE_COMMANDS,
+  ADB_BLOCKED_COMMANDS,
+
+  // Blocked Patterns
+  BLOCKED_PATTERNS,
+  CONTEXT_SENSITIVE_PATTERNS,
+
+  // Classes
+  SecurityError,
+
+  // Safe Mode functions
+  isSafeModeEnabled,
+  getSecurityMode,
+  getSecurityConfig,
+
+  // Input sanitization
+  sanitizeInput,
+  sanitizeFilePath,
+  validateAppId,
+  validateDeviceId,
+
+  // Operation permissions
+  isOperationAllowed,
+  assertOperationAllowed,
+
+  // Command validation
+  isMaestroCommandAllowed,
+  isAdbCommandAllowed,
+  validateCommand,
+  getAllowedCommands,
+
+  // Pattern detection
+  containsBlockedPattern,
+  assertNoBlockedPatterns,
+  sanitizeBlockedPatterns,
+  validateAndSanitizeCommand,
+  checkYamlSecurity,
+  getBlockedPatterns,
+
+  // Logging
+  logSecurityEvent,
+};