SSH Proxy

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.

Highlights

• 🛡 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)

Getting Started

Prerequisites

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.

Start SSH Proxy

Docker

docker run -d \
    -p 8091:22 \
    -v /var/run/docker.sock:/var/run/docker.sock \
    mltooling/ssh-proxy

Kubernetes

If 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.

Connect to Target

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.

Configuration

The container can be configured with the following environment variables (--env):

Features

Access Logging

Logins are logged at /etc/ssh/access.log

Support

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

Contribution

• Pull requests are encouraged and always welcome. Read CONTRIBUTING.md and 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.