SSH MCP Server

# Epic 4: Security and Session Management ## Epic Intent Implement comprehensive security measures and robust session management to ensure secure SSH operations, credential protection, and reliable connection handling across the MCP server lifecycle. ## Story 1: SSH Credential Management As a developer using the SSH MCP server, I want secure credential storage and management so that my SSH authentication information is protected. ### Acceptance Criteria - **Given** SSH credentials need to be stored for connections - **When** credentials are provided to the system - **Then** SSH private keys are loaded from secure file system locations only - **And** private key file permissions are validated (600 or more restrictive) - **And** passwords are never logged or stored in plain text - **And** credential validation occurs before connection attempts - **And** invalid key files are rejected with clear error messages - **And** key passphrases are supported for encrypted private keys - **And** credential information is cleared from memory after use **Security Requirements:** - Private key files must have 600 permissions or more restrictive - No credential information in log files or error messages - Support for RSA, ECDSA, and Ed25519 key types ## Story 2: Connection Authentication Handling As a developer establishing SSH connections, I want robust authentication mechanisms so that I can securely connect to remote servers with various authentication methods. ### Acceptance Criteria - **Given** SSH connection authentication is required - **When** authentication is attempted - **Then** SSH key authentication is tried first if key is provided - **And** password authentication is used as fallback if configured - **And** authentication failures provide specific error types (key rejected, password invalid, etc.) - **And** multiple authentication methods can be attempted in sequence - **And** host key verification prevents man-in-the-middle attacks - **And** known_hosts file is consulted for host key validation - **And** authentication timeouts prevent indefinite hanging **Security Requirements:** - Host key verification must be enabled - Authentication timeout maximum of 30 seconds - Failed authentication attempts are logged for security monitoring ## Story 3: Session Isolation and Security As a developer with multiple SSH sessions, I want proper session isolation so that sessions cannot interfere with each other and security boundaries are maintained. ### Acceptance Criteria - **Given** multiple SSH sessions are active - **When** sessions are operating concurrently - **Then** each session maintains isolated working directories - **And** environment variables are isolated between sessions - **And** process trees are isolated per session - **And** file system access is restricted to user permissions on remote host - **And** session memory is isolated and cleaned up on disconnect - **And** one session cannot read or modify another session's state - **And** session identifiers are unique and non-guessable ## Story 4: Connection Timeout and Recovery As a developer with long-running SSH sessions, I want automatic connection recovery so that temporary network issues don't disrupt my development workflow. ### Acceptance Criteria - **Given** SSH connections may experience network interruptions - **When** connection issues occur - **Then** connection health is monitored with configurable intervals (default: 30 seconds) - **And** failed connections trigger automatic reconnection attempts - **And** exponential backoff is used between reconnection attempts (1s, 2s, 4s, 8s, max 60s) - **And** maximum reconnection attempts are configurable (default: 5) - **And** session state is preserved during reconnection attempts - **And** commands in progress are marked as interrupted - **And** users are notified of connection status changes **Recovery Requirements:** - Initial reconnection attempt within 5 seconds of failure - Session state preservation for up to 10 minutes during reconnection - Clear status reporting during recovery process ## Story 5: Resource Management and Limits As a system administrator, I want resource controls on SSH sessions so that the MCP server operates within defined limits and prevents resource exhaustion. ### Acceptance Criteria - **Given** SSH sessions consume system resources - **When** sessions are created and operated - **Then** maximum concurrent sessions limit is enforced (configurable, default: 10) - **And** memory usage per session is monitored and limited - **And** long-running commands have configurable timeout limits (default: 1 hour) - **And** output buffer sizes are limited to prevent memory exhaustion (max 10MB per session) - **And** inactive sessions are automatically cleaned up after timeout (default: 4 hours) - **And** resource usage metrics are available for monitoring - **And** resource limit violations are logged and reported **Resource Limits:** - Max sessions: 10 (configurable) - Max command runtime: 1 hour (configurable) - Max output buffer: 10MB per session - Session idle timeout: 4 hours (configurable) ## Story 6: Audit Logging and Security Monitoring As a security-conscious developer, I want comprehensive logging of SSH operations so that I can monitor security events and troubleshoot issues. ### Acceptance Criteria - **Given** SSH operations are performed through the MCP server - **When** security-relevant events occur - **Then** all connection attempts are logged with timestamps and source information - **And** authentication failures are logged with failure reasons - **And** command executions are logged with session context - **And** connection state changes are logged - **And** security violations (invalid credentials, failed host key verification) are prominently logged - **And** log entries include session identifiers for correlation - **And** sensitive information (passwords, private keys) is never included in logs **Audit Requirements:** - Structured logging format (JSON) for security analysis - Log rotation to prevent disk space exhaustion - Configurable log levels for different deployment environments ## Story 7: Session Cleanup and Graceful Shutdown As a system operator, I want proper cleanup of SSH sessions so that resources are released and remote connections are closed cleanly. ### Acceptance Criteria - **Given** SSH sessions need to be terminated - **When** session cleanup occurs (manual disconnect, timeout, server shutdown) - **Then** active SSH connections are closed gracefully - **And** running commands are terminated with SIGTERM followed by SIGKILL after timeout - **And** temporary files and session state are cleaned up - **And** monitoring WebSocket connections are closed - **And** memory allocated to sessions is released - **And** cleanup completion is logged - **And** server shutdown waits for active session cleanup (max 30 seconds) **Cleanup Requirements:** - Graceful command termination with 10-second timeout before force kill - Complete cleanup within 30 seconds - No resource leaks after session termination ## Story 8: Security Configuration Validation As a system administrator, I want security configuration validation so that the SSH MCP server operates with secure defaults and rejects insecure configurations. ### Acceptance Criteria - **Given** the MCP server is starting up with configuration - **When** security-related configuration is processed - **Then** SSH protocol version 2 is enforced (no SSHv1) - **And** weak cipher suites are disabled - **And** host key verification cannot be disabled - **And** minimum key sizes are enforced (RSA 2048+, ECDSA 256+) - **And** insecure configuration values prevent server startup - **And** security configuration warnings are logged at startup - **And** default values prioritize security over convenience **Security Standards:** - SSH protocol version 2 only - Strong cipher suites (AES-256, ChaCha20) - Host key verification mandatory - Minimum RSA key size 2048 bits