mcp-maestro-mobile-ai 1.1.0

package/docs/SECURITY.md

@@ -0,0 +1,573 @@
+# Security Model
+
+> **Maestro MCP Server** - Security Documentation
+
+This document describes the security architecture, execution boundaries, threat model, and security best practices for Maestro MCP.
+
+---
+
+## Table of Contents
+
+1. [Security Philosophy](#security-philosophy)
+2. [Trust Model](#trust-model)
+3. [Execution Boundaries](#execution-boundaries)
+4. [Safe Mode](#safe-mode)
+5. [Input Validation](#input-validation)
+6. [Data Security](#data-security)
+7. [Threat Model](#threat-model)
+8. [Security Best Practices](#security-best-practices)
+9. [Incident Response](#incident-response)
+10. [Security Checklist](#security-checklist)
+
+---
+
+## Security Philosophy
+
+### Core Principles
+
+1. **Local-First**: All execution happens on the local machine
+2. **Least Privilege**: Minimum permissions required for operation
+3. **Defense in Depth**: Multiple layers of validation
+4. **Fail Secure**: On error, fail to a safe state
+5. **Transparency**: Clear documentation of all capabilities
+
+### Security Boundaries
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    TRUSTED ZONE                              │
+│  ┌─────────────────────────────────────────────────────┐    │
+│  │                Local Machine                         │    │
+│  │  ┌───────────────┐  ┌───────────────┐               │    │
+│  │  │  MCP Server   │  │   Maestro     │               │    │
+│  │  │  (Node.js)    │◄─┤   CLI         │               │    │
+│  │  └───────────────┘  └───────────────┘               │    │
+│  │         │                  │                         │    │
+│  │         ▼                  ▼                         │    │
+│  │  ┌───────────────────────────────────────────┐      │    │
+│  │  │         Android Device / Emulator          │      │    │
+│  │  │         (via ADB - local connection)       │      │    │
+│  │  └───────────────────────────────────────────┘      │    │
+│  └─────────────────────────────────────────────────────┘    │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              │ ❌ NO EXTERNAL CONNECTIONS
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                    UNTRUSTED ZONE                            │
+│                                                              │
+│  • No cloud services                                        │
+│  • No external APIs                                         │
+│  • No telemetry endpoints                                   │
+│  • No remote storage                                        │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Trust Model
+
+### Trust Hierarchy
+
+| Entity | Trust Level | Validation |
+|--------|-------------|------------|
+| User | Fully Trusted | N/A (local) |
+| AI Client | Trusted with Validation | YAML validation |
+| MCP Server | Trusted | Process isolation |
+| Maestro CLI | Trusted | Command allowlist |
+| ADB | Restricted | Safe Mode enforcement |
+| Device | Sandboxed | App-level isolation |
+
+### AI Client Trust
+
+The AI client (Claude, Copilot) generates Maestro YAML that is:
+
+1. **Validated** before execution
+2. **Restricted** to allowed commands
+3. **Logged** for audit purposes
+4. **Rejectable** if suspicious
+
+```
+AI Client → Generated YAML → [VALIDATION GATE] → Execution
+                                    │
+                                    └── Reject if:
+                                        • Invalid syntax
+                                        • Blocked commands
+                                        • Suspicious patterns
+```
+
+---
+
+## Execution Boundaries
+
+### Allowed Operations
+
+#### Maestro Commands
+
+| Command | Status | Purpose |
+|---------|--------|---------|
+| `maestro test <file>` | ✅ Allowed | Run test flow |
+| `maestro validate <file>` | ✅ Allowed | Validate YAML |
+| `maestro screenshot <path>` | ✅ Allowed | Capture screen |
+| `maestro --version` | ✅ Allowed | Version check |
+
+#### ADB Commands
+
+| Command | Safe Mode | Full Mode | Purpose |
+|---------|-----------|-----------|---------|
+| `adb devices` | ✅ | ✅ | List devices |
+| `adb -s <id> shell pm list packages` | ✅ | ✅ | Check app |
+| `adb -s <id> shell input tap` | ✅ | ✅ | UI interaction |
+| `adb -s <id> shell input text` | ✅ | ✅ | Text input |
+| `adb install` | ❌ | ✅ | Install APK |
+| `adb uninstall` | ❌ | ✅ | Remove app |
+| `adb shell rm` | ❌ | ❌ | **BLOCKED** |
+| `adb shell settings` | ❌ | ❌ | **BLOCKED** |
+| `adb shell am start -a android.intent.action.DELETE` | ❌ | ❌ | **BLOCKED** |
+
+### Blocked Operations
+
+The following are **always blocked** regardless of mode:
+
+```
+❌ BLOCKED OPERATIONS
+├── File system modifications (rm, mv, cp)
+├── System settings changes
+├── Package management (install/uninstall in Safe Mode)
+├── Device wipe / factory reset
+├── Root / superuser commands
+├── Network configuration changes
+├── Arbitrary shell commands
+└── Binary execution
+```
+
+### File System Access
+
+| Path | Access | Purpose |
+|------|--------|---------|
+| `output/` | Read/Write | Test results, screenshots |
+| `.temp/` | Read/Write | Temporary YAML files |
+| `prompts/` | Read | Prompt files |
+| Project root | Read | Configuration files |
+| System paths | ❌ Denied | Security |
+
+---
+
+## Safe Mode
+
+### Overview
+
+Safe Mode is a security feature that restricts operations to read-only and non-destructive actions.
+
+```
+SAFE_MODE=true  (DEFAULT - Recommended)
+SAFE_MODE=false (Full access - Use with caution)
+```
+
+### Safe Mode Restrictions
+
+| Category | Safe Mode ON | Safe Mode OFF |
+|----------|--------------|---------------|
+| Run tests | ✅ | ✅ |
+| Take screenshots | ✅ | ✅ |
+| List devices | ✅ | ✅ |
+| Check app installed | ✅ | ✅ |
+| Install APK | ❌ | ✅ |
+| Uninstall app | ❌ | ✅ |
+| Clear app data | ❌ | ✅ |
+| Device settings | ❌ | ❌ |
+
+### Enabling Safe Mode
+
+```bash
+# Environment variable
+SAFE_MODE=true
+
+# In .env file
+SAFE_MODE=true
+
+# In MCP config
+{
+  "env": {
+    "SAFE_MODE": "true"
+  }
+}
+```
+
+### Safe Mode Enforcement
+
+```javascript
+// Pseudocode for Safe Mode enforcement
+function executeAdbCommand(command) {
+  if (SAFE_MODE) {
+    if (isDestructiveCommand(command)) {
+      throw new SecurityError(
+        "Operation blocked in Safe Mode",
+        "SAFE_MODE_VIOLATION"
+      );
+    }
+  }
+  
+  if (isAlwaysBlocked(command)) {
+    throw new SecurityError(
+      "Operation not allowed",
+      "BLOCKED_OPERATION"
+    );
+  }
+  
+  return execute(command);
+}
+```
+
+---
+
+## Input Validation
+
+### YAML Validation
+
+All AI-generated YAML is validated before execution:
+
+```yaml
+# Validation checks:
+✅ Valid YAML syntax
+✅ Required fields present (appId)
+✅ Known Maestro commands only
+✅ No shell escape attempts
+✅ No path traversal attempts
+```
+
+### Validation Layers
+
+```
+Layer 1: Syntax Validation
+    │
+    ▼
+Layer 2: Schema Validation
+    │
+    ▼
+Layer 3: Command Allowlist
+    │
+    ▼
+Layer 4: Pattern Detection
+    │
+    ▼
+Layer 5: Safe Mode Check
+    │
+    ▼
+✅ Execute
+```
+
+### Blocked Patterns
+
+| Pattern | Reason | Example |
+|---------|--------|---------|
+| Shell injection | Command execution | `; rm -rf /` |
+| Path traversal | File access | `../../../etc/passwd` |
+| Environment expansion | Info disclosure | `$HOME`, `${PATH}` |
+| Command substitution | Execution | `` `command` ``, `$(command)` |
+
+### Input Sanitization
+
+```javascript
+// All user inputs are sanitized
+function sanitizeInput(input) {
+  // Remove null bytes
+  input = input.replace(/\0/g, '');
+  
+  // Escape shell metacharacters
+  input = escapeShellArg(input);
+  
+  // Validate against allowlist
+  if (!isAllowed(input)) {
+    throw new ValidationError("Input not allowed");
+  }
+  
+  return input;
+}
+```
+
+---
+
+## Data Security
+
+### Data Classification
+
+| Data Type | Classification | Handling |
+|-----------|---------------|----------|
+| Prompt files | Internal | User-controlled |
+| Generated YAML | Internal | Temporary, deleted |
+| Test results | Internal | Local storage |
+| Screenshots | Potentially Sensitive | Local storage |
+| Logs | Internal | Local storage |
+
+### Sensitive Data Handling
+
+#### Screenshots
+
+Screenshots may contain sensitive information:
+
+```
+⚠️ WARNING: Screenshots may capture:
+• Personal data on screen
+• Authentication credentials (if visible)
+• Financial information
+• Health information
+• Business confidential data
+
+RECOMMENDATION:
+• Review screenshot contents before sharing
+• Implement screenshot cleanup policy
+• Use dedicated test accounts
+• Mask sensitive data in test apps
+```
+
+#### Test Results
+
+```json
+{
+  "runId": "run-123-1704067200000",
+  "timestamp": "2025-01-01T00:00:00.000Z",
+  "tests": [{
+    "name": "Login test",
+    "success": true,
+    "duration": "3.2s"
+    // No credentials stored
+    // No PII stored
+  }]
+}
+```
+
+### Data Retention
+
+| Data Type | Default Retention | Configurable |
+|-----------|------------------|--------------|
+| Results | Last 50 runs | `MAX_RESULTS` |
+| Screenshots | Same as results | Linked |
+| Logs | Manual cleanup | No |
+| Temp files | Immediate delete | No |
+
+### Data Deletion
+
+```bash
+# Manual cleanup via MCP tool
+cleanup_results --keepLast 10 --deleteScreenshots true
+
+# Or via file system
+rm -rf output/results/*
+rm -rf output/screenshots/*
+```
+
+---
+
+## Threat Model
+
+### Threat Actors
+
+| Actor | Motivation | Capability |
+|-------|------------|------------|
+| Malicious AI Output | Unintended | Limited by validation |
+| Compromised Dependency | Supply chain | Package integrity |
+| Local Attacker | Various | Full local access |
+| Network Attacker | Remote access | None (no network) |
+
+### Attack Vectors
+
+#### 1. Malicious YAML Injection
+
+**Threat**: AI generates malicious YAML that escapes sandbox
+
+**Mitigations**:
+- ✅ YAML syntax validation
+- ✅ Command allowlist
+- ✅ Pattern detection
+- ✅ Safe Mode restrictions
+
+**Risk Level**: Low (multiple validation layers)
+
+#### 2. Dependency Compromise
+
+**Threat**: Malicious code in npm dependencies
+
+**Mitigations**:
+- ✅ Minimal dependencies (5 direct)
+- ✅ Well-known, audited packages
+- ✅ Lock file for version pinning
+- ⚠️ Regular dependency updates
+
+**Risk Level**: Low-Medium (standard npm risk)
+
+#### 3. Path Traversal
+
+**Threat**: Access files outside allowed directories
+
+**Mitigations**:
+- ✅ Path validation
+- ✅ Restricted to output/ directory
+- ✅ No user-controlled paths in execution
+
+**Risk Level**: Low
+
+#### 4. Command Injection
+
+**Threat**: Execute arbitrary commands via input
+
+**Mitigations**:
+- ✅ No shell interpolation
+- ✅ Parameterized command execution
+- ✅ Input sanitization
+
+**Risk Level**: Low
+
+### Security Assumptions
+
+1. **Local execution is trusted** - User has full machine access
+2. **AI client is semi-trusted** - Output is validated
+3. **No network threats** - No external connections
+4. **Device isolation** - Android sandbox is intact
+
+---
+
+## Security Best Practices
+
+### For Users
+
+```
+✅ DO:
+• Keep Safe Mode enabled (default)
+• Use dedicated test devices/emulators
+• Use test accounts with fake data
+• Review generated YAML before execution
+• Regularly clean up screenshots
+• Keep dependencies updated
+
+❌ DON'T:
+• Disable Safe Mode without understanding risks
+• Use production devices for testing
+• Test with real user credentials
+• Store screenshots in version control
+• Ignore security warnings
+```
+
+### For CI/CD
+
+```yaml
+# Recommended CI configuration
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    env:
+      SAFE_MODE: "true"
+      MAX_RESULTS: "10"
+    steps:
+      - name: Run tests
+        run: maestro-mcp run --ci --prompt-file tests.txt
+      
+      - name: Cleanup
+        if: always()
+        run: |
+          rm -rf output/screenshots/*
+          rm -rf output/results/*
+```
+
+### For Enterprise
+
+| Practice | Recommendation |
+|----------|---------------|
+| Network isolation | Run in isolated network segment |
+| Device management | Use dedicated test device pool |
+| Credential management | Use test accounts only |
+| Audit logging | Enable verbose logging |
+| Access control | Restrict who can run tests |
+| Review process | Review AI-generated tests |
+
+---
+
+## Incident Response
+
+### Security Issues
+
+If you discover a security vulnerability:
+
+1. **DO NOT** open a public GitHub issue
+2. **Email**: security@example.com (or create private issue)
+3. **Include**: Description, reproduction steps, impact
+4. **Wait**: For acknowledgment before disclosure
+
+### Response Timeline
+
+| Phase | Timeframe |
+|-------|-----------|
+| Acknowledgment | 24-48 hours |
+| Initial assessment | 72 hours |
+| Fix development | 1-2 weeks |
+| Public disclosure | After fix release |
+
+### Severity Levels
+
+| Level | Description | Response |
+|-------|-------------|----------|
+| Critical | Remote code execution | Immediate patch |
+| High | Local privilege escalation | 48-hour patch |
+| Medium | Information disclosure | Next release |
+| Low | Minor issues | Scheduled fix |
+
+---
+
+## Security Checklist
+
+### Pre-Deployment
+
+```
+□ Safe Mode enabled
+□ APP_ID configured correctly
+□ ANDROID_HOME set (not relying on PATH)
+□ Test device is dedicated/isolated
+□ No production credentials in test data
+□ Screenshot directory is not synced
+□ Log level appropriate for environment
+```
+
+### Ongoing
+
+```
+□ Dependencies updated monthly
+□ Security advisories monitored
+□ Screenshot cleanup scheduled
+□ Result retention policy enforced
+□ Access logs reviewed
+□ Test accounts rotated
+```
+
+### Audit
+
+```
+□ All test runs have audit trail
+□ YAML content preserved for review
+□ Device IDs logged
+□ Timestamps accurate
+□ No sensitive data in logs
+```
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | Jan 2025 | Initial security documentation |
+
+---
+
+## Contact
+
+For security inquiries:
+
+- **Security Issues**: security@example.com
+- **General Questions**: [GitHub Issues](https://github.com/krunal-mahera/mcp-maestro-mobile-ai/issues)
+
+---
+
+*This document is part of the Maestro MCP security program.*
+*Last Updated: January 2025*
+

package/package.json

@@ -0,0 +1,69 @@
+{
+    "name": "mcp-maestro-mobile-ai",
+    "version": "1.1.0",
+    "private": false,
+    "description": "MCP Server for AI-Assisted Mobile Automation using Maestro - Run mobile tests with natural language prompts",
+    "main": "src/mcp-server/index.js",
+    "type": "module",
+    "bin": {
+        "maestro-mcp": "./src/mcp-server/index.js"
+    },
+    "files": [
+        "src/",
+        "prompts/",
+        "templates/",
+        "docs/",
+        "README.md",
+        "LICENSE",
+        "CHANGELOG.md",
+        "ROADMAP.md",
+        "CONTRIBUTING.md"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/krunal-mahera/mcp-maestro-mobile-ai.git"
+    },
+    "homepage": "https://github.com/krunal-mahera/mcp-maestro-mobile-ai#readme",
+    "bugs": {
+        "url": "https://github.com/krunal-mahera/mcp-maestro-mobile-ai/issues"
+    },
+    "scripts": {
+        "start": "node src/mcp-server/index.js",
+        "dev": "node --watch src/mcp-server/index.js",
+        "test:flow": "maestro test",
+        "lint": "eslint src/",
+        "prepublishOnly": "npm run lint"
+    },
+    "keywords": [
+        "mcp",
+        "model-context-protocol",
+        "mobile-automation",
+        "maestro",
+        "react-native",
+        "ai-testing",
+        "android",
+        "ios",
+        "copilot",
+        "claude",
+        "cursor",
+        "testing",
+        "automation",
+        "ai"
+    ],
+    "author": "Krunal Mahera <krunal.mahera@gmail.com>",
+    "license": "MIT",
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.0.0",
+        "dotenv": "^16.4.5",
+        "js-yaml": "^4.1.0",
+        "winston": "^3.17.0",
+        "zod": "^3.23.8"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.39.2",
+        "eslint": "^9.16.0"
+    },
+    "engines": {
+        "node": ">=18.0.0"
+    }
+}

package/prompts/example-login-tests.txt

@@ -0,0 +1,9 @@
+# Login Test Suite
+# Each line below is a separate test prompt
+
+Test that user can login with valid email and password and see the dashboard
+Test that login fails when user enters incorrect password
+Test that login button is disabled when email field is empty
+Test that user sees error message when entering invalid email format
+Test forgot password link navigates to password reset screen
+

package/prompts/example-youtube-tests.txt

@@ -0,0 +1,8 @@
+# YouTube Test Suite
+# Example prompts for testing YouTube app
+
+Test that user can open YouTube and search for TechGuru
+Test that user can play the first video in search results
+Test that user can pause and resume a playing video
+Test that user can subscribe to a channel
+