Dockerized SSH bastion to proxy SSH connections to arbitrary containers.
Getting Started • Highlights • Support • Report a Bug • Contribution
This SSH proxy can be deployed as a standalone docker container that allows to proxy any user SSH connection to arbitrary unexposed containers. This enables users to securely access any container via SSH within a cluster only via a single exposed port and provides full SSH compatibility (e.g. port tunneling, scp, sftp, rsync, sshfs, X11). This proxy has a few security features built-in to make sure that users can only access target containers that they are allowed to.
- 🛡 SSH access to behind-firewall clusters via a single port.
- 🔐 Restrict target containers based on port and DNS pattern.
- 🛠 Full SSH compatibility (port tunneling, scp, sftp, rsync, sshfs).
- 📄 Basic access logging based on user logins.
- 🐳 Easy to deploy via Docker and Kubernetes.
- 🏗 Use it as a base image in your own Docker image to bring the ssh functionality into it (checkout the ml-hub Dockerfile as an example)
The target containers must run an SSH server and provide a valid public key. The ssh-proxy container will try to get a key from a target container via a /publickey endpoint (e.g. http://<containername or podid>:8080/publickey, whereby the port 8080 can be configured via an environment variable); if this does not exist, the ssh-proxy tries to exec into the target container and search for the publickey under $SSH_TARGET_KEY_PATH (default: ~/.ssh/id_ed25519.pub).
ℹ️ The SSH proxy accepts an incoming key, if it belongs to one of the targets key, in other words the proxy/bastion server authorizes all target public keys. It is still not possible to login to the proxy directly. The authorization happens only for creating and tunneling the final connection.
Port and hostname of target containers that users are allowed to access can be restricted via environment variables (see configuration section), but the restrictions can be applied only accross all targets. In Kubernetes mode, the SSH proxy and the SSH targets must be in the same namespace.
We recommend to offer the public key via the /publickey endpoint, as the kubectl exec command can be slow for big clusters. You can also completely avoid those requirements by setting $MANUAL_AUTH_FILE=true and maintaing the proxy's /etc/ssh/authorized_keys_cache file yourself (e.g. by mounting a file at the same location). In this case, you don't have to mount the Docker socket / Kubernetes config into the container. The authorized_keys_cache file has the same format as the standard ssh authorized_keys file.
docker run -d \
-p 8091:22 \
-v /var/run/docker.sock:/var/run/docker.sock \
mltooling/ssh-proxyIf you make a kube config available to the container, either via incluster config (Python code: kubernetes.config.load_incluster_config()) or by mounting it to /root/.kube/config, ssh-proxy also works for tunneling requests in Kubernetes.
ssh \
-o "ProxyCommand=ssh -W %h:%p -p 8091 -i ~/.ssh/<target-key> limited-user@<ssh-proxy-host>" \
-p <target-port> \
-i ~/.ssh/<target-key> \
root@<target-host>Doing this way, the connection from client to target is end-to-end encrypted.
ℹ️ The "<target-host>" host can be the Docker container name or Kubernetes service name. In that case, the bastion has to be in the same Docker network or the connection must be allowed in case of existing Networkpolicies in Kubernetes, respectively.
The container can be configured with the following environment variables (--env):
| Variable | Description | Default |
|---|---|---|
| SSH_PERMIT_TARGET_HOST | Defines which other containers can be ssh targets. The container names must start with the prefix. The ssh connection to the target can only be made for targets where the name matches the given target host. The '*' character can be used as wildcards, e.g. 'workspace-*' would allow connecting to target containers/services which names start with 'workspace-'. | * |
| SSH_PERMIT_TARGET_PORT | Defines on which port the other containers can be reached via ssh. The ssh connection to the target can only be made via this port then. The default value '*' permits any port. | * |
| SSH_TARGET_LABELS | Specify which containers are targeted. Filters containers / pods via these labels. Must be in the form of "label1=value1,label2=value2,label3=value3". Default is empty string which disables filtering. | "" |
| SSH_TARGET_PUBLICKEY_API_PORT | Port where the target container exposes the /publickey endpoint (if used). | 8080 |
| SSH_TARGET_KEY_PATH | The path inside the target containers where the manager looks for a valid public key. Consider that `~` will be resolved to the target container's home. Only used when the target container does not return a public key via the /publickey endpoint. | ~/.ssh/id_ed25519.pub |
| MANUAL_AUTH_FILE | Disables the bastion's public key fetching method and you have to maintain the /etc/ssh/authorized_keys_cache file yourself (e.g. by mounting a respective file there). Only used when the target container does not return a public key via the /publickey endpoint. | false |
Logins are logged at /etc/ssh/access.log
The SSH Proxy project is maintained by @raethlein and @LukasMasuch. Please understand that we won't be able to provide individual support via email. We also believe that help is much more valuable if it's shared publicly so that more people can benefit from it.
| Type | Channel |
|---|---|
| 🚨 Bug Reports |  |
| 🎁 Feature Requests |  |
| 👩💻 Usage Questions |  |
| 🗯 General Discussion | |
- Pull requests are encouraged and always welcome. Read
CONTRIBUTING.mdand check out help-wanted issues. - Submit github issues for any feature enhancements, bugs, or documentation problems.
- By participating in this project you agree to abide by its Code of Conduct.
Licensed Apache 2.0. Created and maintained with ❤️ by developers from SAP in Berlin.
