Name | Date | Size | #Lines | LOC | ||
---|---|---|---|---|---|---|
.. | 03-May-2022 | - | ||||
.github/workflows/ | H | 11-Sep-2021 | - | 137 | 116 | |
cmd/ | H | 11-Sep-2021 | - | 528 | 440 | |
configs/ | H | 11-Sep-2021 | - | 80 | 74 | |
hack/ | H | 11-Sep-2021 | - | 219 | 200 | |
img/ | H | 03-May-2022 | - | |||
pkg/ | H | 11-Sep-2021 | - | 43,044 | 42,230 | |
vendor/ | H | 03-May-2022 | - | 2,395,851 | 1,561,080 | |
.dockerignore | H A D | 11-Sep-2021 | 25 | 1 | 1 | |
.gitignore | H A D | 11-Sep-2021 | 109 | 9 | 9 | |
LICENSE | H A D | 11-Sep-2021 | 1 KiB | 22 | 17 | |
README.md | H A D | 11-Sep-2021 | 8.5 KiB | 221 | 155 | |
build.sh | H A D | 11-Sep-2021 | 906 | 40 | 26 | |
go.mod | H A D | 11-Sep-2021 | 1.1 KiB | 32 | 28 | |
go.sum | H A D | 11-Sep-2021 | 60.3 KiB | 624 | 623 | |
main.go | H A D | 11-Sep-2021 | 83 | 8 | 5 |
README.md
1# [Rospo](https://github.com/ferama/rospo) 2[![Go Reference](https://pkg.go.dev/badge/github.com/ferama/rospo.svg)](https://pkg.go.dev/github.com/ferama/rospo) 3[![Go Report Card](https://goreportcard.com/badge/github.com/ferama/rospo)](https://goreportcard.com/report/github.com/ferama/rospo) 4[![codecov](https://codecov.io/gh/ferama/rospo/branch/main/graph/badge.svg)](https://codecov.io/gh/ferama/rospo) 5[![Docker Pulls](https://img.shields.io/docker/pulls/ferama/rospo.svg)](https://hub.docker.com/r/ferama/rospo/) 6 7 8 9 10Rospo is a tool meant to create reliable ssh tunnels. 11It embeds an ssh server too if you want to reverse proxy a secured 12shell 13 14It's meant to make ssh tunnels fun and understendable again 15 16### Table of Contents 171. [Why Rospo?](#why-rospo) 182. [Quick command line usage](#quick-command-line-usage) 193. [Rospo UI](#rospo-ui) 204. [Scenarios](#scenarios) 21 * [Example scenario: Windows (WSL || PowerShell) reverse shell](#example-scenario-windows-reverse-shell) 22 * [Example scenario: multiple complex tunnels](#example-scenario-multiple-complex-tunnels) 23 * [Example scenario: kubernetes service exporter](#example-scenario-kubernetes-service-exporter) 245. [How to Install](#how-to-install) 25 26 27## Why Rospo 28I wanted an easy to use and reliable ssh tunnel tool. The available alternatives don't fully satisfy me and don't support all the features I need (as the embedded sshd server for example, or an out of the box connection monitoring mechanism) so I wrote my own 29 30## Quick command line usage 31Rospo supports keys based auth and password auth. Keys based one is always the preferred, so it is better if *identity*, *authorized_keys* etc are always correctly setup. 32 33Usage example: 34 35Starts an embedded ssh server and reverse proxy the port (2222 by default) to remote_server 36 37``` 38$ rospo revshell user@server:port 39``` 40 41Forwards the local 5000 port to the remote 6000 on the remote_server 42 43``` 44$ rospo tun forward -l :5000 -r :6000 user@server:port 45``` 46 47Get more detailed help on each command runnig 48``` 49$ rospo tun forward --help 50$ rospo tun reverse --help 51$ rospo sshd --help 52``` 53 54For more complex use cases and more options, you can use a config file 55``` 56$ rospo config.yaml 57``` 58 59Look at the [config_template.yaml](https://github.com/ferama/rospo/blob/main/configs/config_template.yaml) for all the available options. 60 61A config file is required for example to setup pipes. Pipes let's you do things like: 62 631. opening a socket on locahost on port 1234 642. copy all packets from and to local port 1234 to remote reachable host:whathever_port 65 66This is handy in some situations when you want to use a host as bridge for a service (its almost like a **socat** bidirectional pipe but without the need for another tool) 67 68## Rospo UI 69Rospo supports a cool ui too. The ui will let you handle tunnels and pipes configuration at runtime through the web interface. 70You can start/stop new tunnels and pipes at runtime. 71 72Pipes and tunnels that are configured through the rospo config file will not be administrable from the ui. 73 74![Image of Home](https://raw.githubusercontent.com/ferama/rospo/main/img/home.png) 75 76![Image of tunnels](https://raw.githubusercontent.com/ferama/rospo/main/img/tunnels.png) 77 78![Image of tunnels](https://raw.githubusercontent.com/ferama/rospo/main/img/pipes.png) 79 80## Scenarios 81 82### Example scenario: Windows reverse shell 83Why use an embedded sshd server you might ask me. 84Suppose you have a Windows WSL instance that you want to access remotely without complicated setups on firewalls and other hassles and annoyances. With **rospo** you can do it in ONE simple step: 85 86``` 87$ rospo revshell remote_ssh_server 88``` 89 90This command will run an embedded sshd server on your wsl instance and reverse proxy its port to the `remote_ssh_server` 91 92The only assumption here is that you have access to `remote_ssh_server`. 93The command will open a socket (on port 2222 by default) into `remote_ssh_server` that you can use to log back to WSL using a standard ssh client with a command like: 94 95``` 96$ ssh -p 2222 localhost 97``` 98 99Or even better (why not!) with rospo you can reverse proxy a powershell. 100Using rospo for windows: 101``` 102rospo.exe revshell remote_ssh_server 103``` 104 105 106 107### Example scenario: multiple complex tunnels 108 109Rospo supports multiple tunnels on the same ssh connetion. To exploit the full power of rospo for more complex cases, you should/need to use a scenario config file. 110Let's define one. Create a file named `config.yaml` with the following contents 111```yaml 112sshclient: 113 server: myuser@remote_server_address 114 identity: "~/.ssh/id_rsa" 115 jump_hosts: 116 - uri: anotheruser@jumphost_address 117 identity: "~/.ssh/id_rsa" 118 119tunnel: 120 - remote: ":8000" 121 local: ":8000" 122 forward: yes 123 - remote: ":9999" 124 local: ":9999" 125 forward: yes 126 - remote: ":5000" 127 local: ":5000" 128 forward: no 129``` 130 131Launch rospo using the config file instead of the cli parameters: 132``` 133$ rospo config.yaml 134``` 135 136What's happens here is that rospo will connect to `remote_server_address` through the `jumphost_address` server and will: 137 1381. open a socket on the local machine listening on port 8000 that forwards all the traffic to the service listening on port 8000 on the `remote_server_address` machine 1392. open a socket on the local machine listening on port 9999 that forwards all the traffic to the service listening on port 9999 on the `remote_server_address` machine 1403. open a socket on the remote machine listening on port 5000 that forwards all the traffic from remote machine to a local service (on the local machine) listening on port 5000 141 142But these are just an examples. Rospo can do a lot more. 143 144Tunnels are fully secured using standard ssh mechanisms. Rospo will generate server identity file on first run and uses standard `authorized_keys` and user `known_hosts` files. 145 146Rospo tunnel are monitored and keeped up in the event of network issues. 147 148 149### Example scenario: kubernetes service exporter 150 151Many times during development on k8s you need to port-forward some of the pods services for local development and/or tests. You need the port forward maybe because that services are not meant to be exposed through the internet or for whatever reason. 152 153Rospo can come to the rescue here. You can create a `rospo.conf` like this: 154```yaml 155sshclient: 156 identity: "/etc/rospo/id_rsa" 157 server: my-rospo-or-standard-sshd-server:2222 158 known_hosts: "/etc/rospo/known_hosts" 159 160tunnel: 161 - remote: "0.0.0.0:9200" 162 local: ":9200" 163 forward: no 164 - remote: "0.0.0.0:8080" 165 local: ":8080" 166 forward: no 167 168pipe: 169 - remote: "elasticsearch-master.mynamespace:9200" 170 local: ":9200" 171 - remote: "demo-app.mynamespace:8080" 172 local: ":8080" 173``` 174 175You need to create the keys accordingly and put them correctly on the target server. After that you can run a kubernetes pod that keeps up the tunnels and let you securely access the services from a machine inside your local network. 176Please refer to the example in [./hack/k8s](./hack/k8s) for more details. 177 178In this scenario the k8s pods act as a bridge between kubernetes services and the reverse tunnels. You are going to use `pipes` to copy the connections from the services to the rospo pod. The pipes in the example will open 2 sockets locally inside the pod: 179 1. a socket on local port **9200** for the **elasticsearch-master.mynamespace:9200** service 180 2. a socket on local port **8080** for the **demo-app.mynamespace:8080** service 181 182 Finally you are going to reverse forward the pod local ports to the desired host (my-rospo-or-standard-sshd-server:2222 in the example above) 183 184## How to Install 185 186Rospo actually full supports *nix oses and Windows 10 187Grab the latest binary release from here [https://github.com/ferama/rospo/releases/latest](https://github.com/ferama/rospo/releases/latest) or use the copy and paste curl below 188 189Alternatively you can use the docker ditribution where useful/needed. Look at an example on kubernetes here [./hack/k8s](./hack/k8s) 190 191 192#### Linux amd64 193``` 194curl -L https://github.com/ferama/rospo/releases/latest/download/rospo-linux-amd64 --output rospo && chmod +x rospo 195``` 196 197#### Linux arm64 198``` 199curl -L https://github.com/ferama/rospo/releases/latest/download/rospo-linux-arm64 --output rospo && chmod +x rospo 200``` 201 202#### Linux arm 203``` 204curl -L https://github.com/ferama/rospo/releases/latest/download/rospo-linux-arm --output rospo && chmod +x rospo 205``` 206 207#### Mac OS 208``` 209curl -L https://github.com/ferama/rospo/releases/latest/download/rospo-darwin-arm64 --output rospo && chmod +x rospo 210``` 211 212#### Windows 213 214You will require Windows 10 215 216``` 217(New-Object System.Net.WebClient).DownloadFile("https://github.com/ferama/rospo/releases/latest/download/rospo-windows-amd64.exe", "rospo.exe") 218``` 219 220 221