Security: SSH Key Management

Relevant source files

The following files were used as context for generating this wiki page:

• internal/dokku-api/ssh_auth.go
• internal/dokku-api/ssh_config.go
• internal/dokku-api/ssh_integration.go
• internal/dokku-api/ssh_auth_test.go
• scripts/setup-dokku-local.sh
• README.md
• internal/server-plugins/core/domain/entities.go

The dokku-mcp server interacts with a Dokku instance by executing commands over SSH. The SSH Key Management system is responsible for securely configuring, authenticating, and managing these connections. It provides a robust framework for defining connection parameters, determining the appropriate authentication method, and constructing secure SSH commands.

The system is designed with a clear separation of concerns, dividing responsibilities between configuration, authentication, and connection management. This ensures that connection details are validated, authentication follows a clear priority, and commands are prepared safely before execution.

Architecture Overview

The SSH management system is composed of three primary components: SSHConfig, SSHAuthService, and SSHConnectionManager. They work together to establish a connection to the Dokku host.

This diagram shows the relationship between the main components of the SSH management system.

SSH Configuration (SSHConfig)

The SSHConfig struct is the foundation for defining how to connect to a Dokku host. It holds all necessary parameters and includes extensive validation to prevent misconfigurations and basic security vulnerabilities.

Sources: internal/dokku-api/ssh_config.go:10-16

Configuration Parameters

Field	Type	Description
host	string	The hostname or IP address of the Dokku server.
port	int	The SSH port on the Dokku server.
user	string	The SSH user, typically dokku.
keyPath	string	The file path to the SSH private key. If empty, ssh-agent is used.
timeout	time.Duration	The connection timeout for the SSH command.
verified	bool	A flag indicating if the connection configuration has been successfully tested.

Sources: internal/dokku-api/ssh_config.go:10-16

Configuration Validation

Before an SSHConfig object is created, a series of validation checks are performed to ensure the parameters are safe and correctly formatted.

Parameter	Validation Rule	Error Message
host	Cannot be empty. Max length 255. Must match hostname pattern.	SSH host cannot be empty
port	Must be between 1 and 65535.	invalid SSH port
user	Cannot be empty. Max length 32. Must match username pattern.	SSH user cannot be empty
keyPath	Cannot contain .. to prevent directory traversal. Max length 4096.	SSH key path cannot contain '..'
timeout	Cannot be negative. Cannot exceed 10 minutes.	SSH timeout cannot be negative

Sources: internal/dokku-api/ssh_config.go:214-263

A key security check prevents path traversal attacks when specifying a key file:

// internal/dokku-api/ssh_config.go:252-255
// Basic security checks
if strings.Contains(keyPath, "..") {
    return fmt.Errorf("SSH key path cannot contain '..'")
}

Base SSH Arguments

To ensure consistency and security, SSHConfig provides a set of base arguments that are included in every SSH command.

Argument	Purpose
-t	Allocates a pseudo-terminal, which is required by Dokku for many commands.
-o LogLevel=QUIET	Suppresses verbose SSH logging.
-o StrictHostKeyChecking=no	Disables host key checking, simplifying connections in dynamic environments.
-o ConnectTimeout=<seconds>	Sets the connection timeout based on the timeout configuration field.
-p <port>	Specifies the SSH connection port.

Sources: internal/dokku-api/ssh_config.go:94-101

SSH Authentication (SSHAuthService)

The SSHAuthService is responsible for determining the best available authentication method based on a defined priority. It supports using a specific key file or an ssh-agent.

Sources: internal/dokku-api/ssh_auth.go:18-25

Authentication Priority

The service follows a strict order of precedence to select an authentication method. This logic is encapsulated in the DetermineAuthMethod function.

This flowchart illustrates the decision-making process for selecting an SSH authentication method.

The priority is as follows:

1. Configured Key: If keyPath is provided in the configuration and the file is accessible, it is used.
2. SSH-Agent: If a key is not configured, the service checks if ssh-agent is running and has identities loaded by checking the SSH_AUTH_SOCK environment variable and running ssh-add -l.
3. Default Key: If ssh-agent is not available, it falls back to checking for the existence of ~/.ssh/id_rsa.
4. Fallback: If none of the above methods are available, it defaults to attempting to use ssh-agent anyway.

Sources: internal/dokku-api/ssh_auth.go:59-106, internal/dokku-api/ssh_auth_test.go:111-146

Authentication Caching

To improve performance and reduce redundant checks, the determined authentication method is cached for 60 minutes. The cache is invalidated if InvalidateCache() is called.

Sources: internal/dokku-api/ssh_auth.go:24-27, 40-50, 109-114

Connection Management (SSHConnectionManager)

The SSHConnectionManager is the central orchestrator that combines SSHConfig and SSHAuthService to prepare and execute SSH commands.

Sources: internal/dokku-api/ssh_integration.go:10-14

Command Preparation Flow

The PrepareSSHCommand function is responsible for assembling the final command-line arguments for the ssh executable.

This sequence diagram shows how SSHConnectionManager interacts with other components to build a full SSH command.

Setup and Configuration Examples

The project provides scripts and documentation that illustrate how to configure SSH key management in practice.

Local Development Setup

The scripts/setup-dokku-local.sh script automates the setup of a local Dokku instance for development. As part of this process, it generates a dedicated SSH key pair and configures it for use.

1. Generates a new SSH key: A key is created at .ssh/dokku_mcp_test if one doesn't exist.
   Sources: scripts/setup-dokku-local.sh:37-43
2. Adds the public key to Dokku: The public key is added to the local Dokku container using dokku ssh-keys:add.
   Sources: scripts/setup-dokku-local.sh:47-48
3. Creates a local config.yaml: A configuration file is generated, pointing to the new key.
   Sources: scripts/setup-dokku-local.sh:68-87

Example config.yaml snippet from the setup script:

# SSH configuration for local Dokku instance
ssh:
  host: "127.0.0.1"
  port: 3022
  user: "dokku"
  key_path: ".ssh/dokku_mcp_test"

Sources: scripts/setup-dokku-local.sh:83-87

Client Configuration (mcp.json)

End-users configure the dokku-mcp server via a JSON file, where they can specify the SSH connection details through environment variables passed to the server process.

{
  "mcpServers": {
    "dokku": {
      "command": "/home/user/dokku-mcp/build/dokku-mcp",
      "args": [],
      "env": {
        "DOKKU_MCP_SSH_HOST": "127.0.0.1",
        "DOKKU_MCP_SSH_KEY_PATH": "/home/user/.ssh/id_rsa",
        "DOKKU_MCP_SSH_PORT": "22",
        "DOKKU_MCP_SSH_USER": "dokku"
      }
    }
  }
}

Sources: README.md:40-54

Summary

The SSH Key Management system in dokku-mcp provides a secure and flexible mechanism for communicating with a Dokku host. It enforces strong validation on connection parameters, uses a clear and logical priority system for selecting authentication methods, and centralizes the construction of SSH commands to ensure consistency. Through components like SSHConfig, SSHAuthService, and SSHConnectionManager, the system effectively isolates concerns, making it robust and maintainable. The inclusion of setup scripts and clear configuration examples further aids developers and users in establishing secure connections.