Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ml-tooling/ssh-proxy

🐳 Dockerized SSH bastion to proxy SSH connections to arbitrary containers.
https://github.com/ml-tooling/ssh-proxy

bastion docker gateway jumpserver kubernetes ssh-bastion ssh-server ssh-tunnel

Last synced: about 1 month ago
JSON representation

🐳 Dockerized SSH bastion to proxy SSH connections to arbitrary containers.

Host: GitHub
URL: https://github.com/ml-tooling/ssh-proxy
Owner: ml-tooling
License: apache-2.0
Created: 2019-06-18T12:33:43.000Z (over 5 years ago)
Default Branch: master
Last Pushed: 2020-08-04T09:53:28.000Z (over 4 years ago)
Last Synced: 2024-11-02T15:36:29.970Z (about 1 month ago)
Topics: bastion, docker, gateway, jumpserver, kubernetes, ssh-bastion, ssh-server, ssh-tunnel
Language: Python
Homepage:
Size: 121 KB
Stars: 80
Watchers: 6
Forks: 16
Open Issues: 1
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md

Awesome Lists containing this project

awesome-ssh - ssh-proxy - tooling/ssh-proxy.svg?style=social&label=stars)](https://github.com/ml-tooling/ssh-proxy) - Dockerized SSH bastion to proxy SSH connections to arbitrary containers. (Apps / Servers)
awesome-starred - ml-tooling/ssh-proxy - 🐳 Dockerized SSH bastion to proxy SSH connections to arbitrary containers. (kubernetes)

README

        


    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](https://github.com/ml-tooling/ml-hub/blob/1ab1c6b1b4b4b8a6fd2f321ccfb9c8f6f0e0c6eb/Dockerfile#L1) 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://:8080/publickey`, whereby the port 8080 can be configured via an [environment variable]($SSH_TARGET_PUBLICKEY_API_PORT)); 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](#configuration)), 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

```bash

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

```bash

ssh \

    -o "ProxyCommand=ssh -W %h:%p -p 8091 -i ~/.ssh/ limited-user@" \

    -p  \

    -i ~/.ssh/ \

    root@

```

Doing this way, the connection from client to target is end-to-end encrypted.

> ℹ️ _The "\" 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](https://twitter.com/raethlein) and [@LukasMasuch](https://twitter.com/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`](https://github.com/ml-tooling/ssh-proxy/tree/master/CONTRIBUTING.md) and check out [help-wanted](https://github.com/ml-tooling/ssh-proxy/issues?utf8=%E2%9C%93&q=is%3Aopen+is%3Aissue+label%3A"help+wanted"+sort%3Areactions-%2B1-desc+) issues.

- Submit github issues for any [feature enhancements](https://github.com/ml-tooling/ssh-proxy/issues/new?assignees=&labels=feature-request&template=02_feature-request.md&title=), [bugs](https://github.com/ml-tooling/ssh-proxy/issues/new?assignees=&labels=bug&template=01_bug-report.md&title=), or [documentation](https://github.com/ml-tooling/ssh-proxy/issues/new?assignees=&labels=enhancement%2C+docs&template=03_documentation.md&title=) problems.

- By participating in this project you agree to abide by its [Code of Conduct](https://github.com/ml-tooling/ssh-proxy/tree/master/CODE_OF_CONDUCT.md).

---

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