Skip to content

Latest commit

 

History

History
149 lines (115 loc) · 10.1 KB

README.md

File metadata and controls

149 lines (115 loc) · 10.1 KB
Raw

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):

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

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

Licensed Apache 2.0. Created and maintained with ❤️ by developers from SAP in Berlin.