EGH Research

# Admin Password Protection for Unrestricted Bash Operations ## 🔒 Security Feature Overview **Purpose**: Protect unrestricted bash access in `server-universal.js` with password authentication and rate limiting. ## 🎯 How It Works ### **Password Requirement** - **Default Password**: `admin18401844` - **Environment Variable**: `ADMIN_PASSWORD` (overrides default) - **Can Be Disabled**: Set `REQUIRE_ADMIN_PASSWORD=false` (not recommended) ### **User Experience** #### **AI Assistant Usage** ```javascript // ❌ Will be rejected { "name": "bash", "arguments": { "command": "ls -la" // adminPassword: missing } } // ✅ Will work { "name": "bash", "arguments": { "command": "ls -la", "adminPassword": "admin18401844" } } ``` #### **Error Messages Users See** 1. **No Password**: `"Admin password required for unrestricted bash access. Provide adminPassword parameter."` 2. **Wrong Password**: `"Admin password required for unrestricted bash access. Provide adminPassword parameter."` 3. **Account Locked**: `"Too many failed attempts. Account locked for X minutes."` ### **Security Features** #### **🔒 Lockout Mechanism** - **Failed Attempts**: 3 strikes - **Lockout Duration**: 5 minutes - **Per Client Tracking**: Each client tracked separately - **Automatic Reset**: After successful access #### **📊 Attempt Logging** ``` ❌ Failed admin attempt from stdio-client: 1/3 ❌ Failed admin attempt from stdio-client: 2/3 ❌ Failed admin attempt from stdio-client: 3/3 ✅ Successful admin access from stdio-client ``` #### **🛡️ Protection Scope** - **Protected**: `bash` tool in `server-universal.js` - **Unprotected**: All other tools (search, database operations, etc.) - **Optional**: Can be disabled via environment variable ## 🔧 Configuration Options ### **Environment Variables** ```bash # Set custom password export ADMIN_PASSWORD="your-secure-password" # Disable password protection (NOT RECOMMENDED) export REQUIRE_ADMIN_PASSWORD="false" # Default settings # ADMIN_PASSWORD="admin18401844" # REQUIRE_ADMIN_PASSWORD="true" ``` ### **Security Settings** ```javascript const ADMIN_CONFIG = { password: process.env.ADMIN_PASSWORD || 'admin18401844', requirePassword: process.env.REQUIRE_ADMIN_PASSWORD !== 'false', logAttempts: true, maxAttempts: 3, lockoutDuration: 5 * 60 * 1000 // 5 minutes }; ``` ## 🚀 Usage Examples ### **For AI Assistants** ```bash # Correct usage curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "bash", "arguments": { "command": "echo \"Secure access!\"", "adminPassword": "admin18401844" } } }' ``` ### **For Developers** ```javascript // In MCP client const result = await mcpClient.callTool('bash', { command: 'ls -la', adminPassword: 'admin18401844' }); ``` ### **For Testing** ```bash # Run test suite node test-admin-bash.cjs # Test with custom password ADMIN_PASSWORD="test123" node apps/local-server/src/server-universal.js ``` ## 🔍 Monitoring & Logs ### **Server Logs** ``` 🛠️ Tool call: bash { command: 'ls -la', adminPassword: '***' } ❌ Failed admin attempt from stdio-client: 1/3 ✅ Successful admin access from stdio-client ``` ### **Lockout Tracking** - **Memory**: `Map<clientIP, {count, lastAttempt}>` - **Duration**: 5 minutes per lockout - **Reset**: On successful authentication - **Scope**: Per client identifier ## 🚨 Security Considerations ### **✅ What's Protected** - Unrestricted bash command execution - System-level operations - File system access - Network operations ### **⚠️ What's Not Protected** - Database operations (search, books, content) - GitHub PAT management - Local chat AI launching - HTTP file serving ### **🔐 Best Practices** 1. **Change Default Password**: Set `ADMIN_PASSWORD` environment variable 2. **Monitor Logs**: Watch for failed attempts 3. **Use Strong Passwords**: Custom passwords instead of default 4. **Regular Rotation**: Change passwords periodically 5. **Access Control**: Limit who knows the admin password ## 🆚 Comparison: Protected vs Unprotected | Feature | Protected | Unprotected | |----------|------------|-------------| | Bash Access | ✅ Password Required | ❌ Open Access | | Rate Limiting | ✅ 3 Attempts/5min | ❌ Unlimited | | Attempt Logging | ✅ Full Tracking | ❌ No Logs | | Lockout | ✅ Automatic | ❌ None | | Configuration | ✅ Flexible | ❌ Fixed | ## 🎭 User Scenarios ### **Scenario 1: Legitimate User** ``` User: "I need to run system commands" AI: "Please provide admin password for bash access" User: "admin18401844" AI: "✅ Executing your command securely..." ``` ### **Scenario 2: Unauthorized Access** ``` User: "Run rm -rf /" AI: "❌ Admin password required for bash operations" User: "guess123" AI: "❌ Authentication failed - 2 attempts remaining" User: "guess456" AI: "🔒 Account locked for 5 minutes due to failed attempts" ``` ### **Scenario 3: Developer Testing** ```bash # Test protection is working node test-admin-bash.cjs # Test with custom password ADMIN_PASSWORD="dev123" node apps/local-server/src/server-universal.js # Disable for development (DANGEROUS) REQUIRE_ADMIN_PASSWORD="false" node apps/local-server/src/server-universal.js ``` ## 🔧 Implementation Details ### **Code Location**: `apps/local-server/src/server-universal.js` ### **Protection Function**: `verifyAdminPassword(password, clientIP)` ### **Integration Point**: `bash` tool handler in `handleToolCall()` ### **Test Suite**: `test-admin-bash.cjs` ### **Security Architecture** ``` ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ AI Client │───▶│ Admin Password │───▶│ Bash Exec │ │ │ │ Verification │ │ │ │ adminPassword │ │ │ │ Unrestricted │ │ parameter │ │ ✓ Valid/✗ Fail│ │ Commands │ └─────────────────┘ └──────────────────┘ └─────────────────┘ ``` ## 📋 Checklist for Secure Deployment - [ ] **Change default password** via `ADMIN_PASSWORD` env var - [ ] **Test protection** with `node test-admin-bash.cjs` - [ ] **Monitor logs** for failed attempts - [ ] **Document access** for authorized users - [ ] **Review security** settings regularly - [ ] **Backup configuration** of environment variables --- **Status**: ✅ **IMPLEMENTED AND TESTED** The admin password protection system provides enterprise-grade security for unrestricted bash operations while maintaining usability for legitimate users.