Security Overview
Relevant source files
The following files were used as context for generating this wiki page:
The Dokku MCP server acts as a bridge, exposing Dokku's management capabilities to Large Language Models (LLMs) through the Model Context Protocol (MCP). The security model is primarily focused on controlling and sanitizing the Dokku commands executed via SSH. This is achieved through a multi-layered approach including command validation, a configurable command blacklist, secure SSH parameterization, and transport layer controls.
The project is in an early stage of development and is not recommended for production use. The security model is evolving, with plans to move from a blacklist to a more restrictive allow-list model in the future.
Sources: README.md:9-10, README.md:46-47
Command Execution Security
The core of the security model resides within the dokku-api client, which is responsible for validating and executing all commands sent to the Dokku host. Every command undergoes a strict validation process before it is executed.
Sources: internal/dokku-api/client.go:16-56
Command Validation Flow
The ValidateCommand function in the client.go file orchestrates a series of security checks. A command is only executed if it passes all validation steps.
The diagram below illustrates the command validation process.
Sources: internal/dokku-api/client.go:16-56
Dangerous Character Filtering
To prevent command injection attacks, the ValidateCommand function explicitly blocks a set of dangerous characters from appearing in both the command name and its arguments.
| Blocked Character | Description |
|---|---|
; | Command separator |
& | Background process operator |
| ` | ` |
` | Command substitution |
$ | Variable expansion / Command substitution |
( ) | Subshell execution |
{ } | Command grouping |
< > | I/O redirection |
\n \r | Newline / Carriage return |
Sources: internal/dokku-api/client.go:26-36
Command Blacklisting
A key security feature is the ability to blacklist specific Dokku commands. This is a runtime configuration that prevents potentially destructive or sensitive commands from being executed.
Configuration
The blacklist is configured via an environment variable or a configuration file.
| Configuration Method | Key | Example Value |
|---|---|---|
| Environment Variable | DOKKU_MCP_SECURITY_BLACKLIST | "destroy,uninstall,remove" |
config.yaml | security.blacklist | ["destroy", "uninstall"] |
Sources: README.md:29, scripts/setup-dokku-local.sh:100-103
Behavior
- The blacklist check is the first validation step after checking for an empty command.
- It performs a partial string match (
strings.Contains). This means blacklistingdestroywill blockapps:destroy,plugin:destroy, etc. - The project's roadmap includes a plan to eventually replace this blacklist with a more secure, explicit allow-list.
Sources: internal/dokku-api/client.go:21-25, internal/dokku-api/client_blacklist_test.go:34-40, README.md:47
SSH Connection Security
All Dokku commands are executed over SSH. The system includes several measures to configure and harden these connections.
SSH Configuration
The connection to the Dokku host is configured via environment variables or a config.yaml file. A dedicated, non-root user (dokku) and key-based authentication are used.
| Parameter | Environment Variable | config.yaml Key | Description |
|---|---|---|---|
| Host | DOKKU_MCP_SSH_HOST | ssh.host | The hostname or IP of the Dokku server. |
| Port | DOKKU_MCP_SSH_PORT | ssh.port | The SSH port on the Dokku server. |
| User | DOKKU_MCP_SSH_USER | ssh.user | The SSH user, typically dokku. |
| Private Key Path | DOKKU_MCP_SSH_KEY_PATH | ssh.key_path | Absolute path to the SSH private key. |
Sources: README.md:29-34, scripts/setup-dokku-local.sh:94-98
SSH Parameter Hardening
The SSH command itself is constructed with specific arguments to improve security and stability:
-t: Allocates a pseudo-terminal (PTY), which is required by Dokku for many commands.-o LogLevel=QUIET: Suppresses verbose SSH logging.-o StrictHostKeyChecking=no: Disables host key checking. This is noted in local development scripts for convenience.-o UserKnownHostsFile=/dev/null: Prevents writing to or reading from the known hosts file in local development setups.-i /path/to/key: Specifies the identity file (private key) for authentication.
Sources: internal/dokku-api/ssh_integration_test.go:63-74, scripts/setup-dokku-local.sh:66-73
SSH Key Path Validation
To prevent path traversal attacks, the SSH configuration validation ensures that the provided key_path does not contain ...
Sources: internal/dokku-api/ssh_integration_test.go:303-309
Input Validation
In addition to command injection prevention, the system incorporates domain-specific input validation.
- Application Name Validation: The
appplugin uses aValidationServiceto check application names. It validates against patterns (e.g.,^[a-z0-9-]+$), reserved names (e.g.,dokku), and provides warnings for non-optimal formats. - Development Practice: The project's contribution guidelines mandate that "proper input validation and sanitization" are part of the code review checklist, encouraging a security-conscious development culture.
Sources: internal/server-plugins/app/domain/application-validation.service.go:50-64, CONTRIBUTING.md:58
Transport Layer Security
Security is also considered at the transport layer, which handles communication between the MCP client (e.g., an IDE) and the dokku-mcp server.
CORS Configuration
When using the sse (Server-Sent Events) transport mode over HTTP, the server provides configurable Cross-Origin Resource Sharing (CORS) middleware. This is disabled by default, with the underlying mcp-go library defaulting to Access-Control-Allow-Origin: *. For more secure deployments, custom CORS policies can be enabled.
transport.cors Key | Type | Description |
|---|---|---|
enabled | boolean | Enables or disables the custom CORS middleware. |
allowed_origins | array[string] | List of allowed origins. Supports wildcards (*). |
allowed_methods | array[string] | Configurable allowed HTTP methods. |
allowed_headers | array[string] | Configurable allowed HTTP headers. |
Sources: CHANGELOG.md:11-17, README.md:154-165