SSH Piper works as a proxy-like ware, and route connections by username, src ip , etc.

+---------+                      +------------------+          +-----------------+
|         |                      |                  |          |                 |
|   Bob   +----ssh -l bob----+   |   SSH Piper   +------------->   Bob' machine  |
|         |                  |   |               |  |          |                 |
+---------+                  |   |               |  |          +-----------------+
                             +---> pipe-by-name--+  |                             
+---------+                  |   |               |  |          +-----------------+
|         |                  |   |               |  |          |                 |
|  Alice  +----ssh -l alice--+   |               +------------->  Alice' machine |
|         |                      |                  |          |                 |
+---------+                      +------------------+          +-----------------+


 Downstream                         SSH Piper                       Upstream                     

Just run showme.sh in sshpiperd example directory or Copy paste command below to run

git clone https://github.com/tg123/sshpiper
cd sshpiper
git submodule update --init --recursive

cd sshpiperd/example/
./showme.sh

the example script will setup a sshpiper server using

bitbucket -> [email protected]:22 # ssh 127.0.0.1 -p 2222 -l bitbucket
github -> [email protected]:22 # ssh 127.0.0.1 -p 2222 -l github
gitlab -> [email protected]:22 # ssh 127.0.0.1 -p 2222 -l gitlab

connect to gitlab

$ ssh 127.0.0.1 -p 2222 -l gitlab
Permission denied (publickey).

connect to github.com

$ ssh 127.0.0.1 -p 2222 -l github
Permission denied (publickey).

git clone https://github.com/tg123/sshpiper.git
cd sshpiper
git submodule update --init --recursive
cd sshpiperd
go build

docker run farmer1992/sshpiperd

Run with Workding Dir upstream driver

docker run -d -p 2222:2222 \
  -v /etc/ssh/ssh_host_rsa_key:/etc/ssh/ssh_host_rsa_key \
  -v /YOUR_WORKING_DIR:/var/sshpiper \
  farmer1992/sshpiperd

Run with Additional Challenge

sudo snap install sshpiperd

configure with snap

sudo snap set sshpiperd 'port=3333'

sudo snap restart sshpiperd

NOTE:

• Default working dir for snap verion is /var/snap/sshpiperd/common

sshpiper provides 3 pluginable components to highly customize your piper

• Upstream Driver
• Additional Challenge
• Auditor

sshpiperd daemon -h to learn more

Upstream driver helps sshpiper to find which upstream host to connect and how to connect.

For example, you can change the username when connecting to upstream sshd by config upstream driver

Available Upstream Drivers

• Workding Directory

  Working Dir is a /home-like directory. SSHPiperd read files from workingdir/[username]/ to know upstream's configuration.

• YAML

  YAML based config file driver

• gRPC Driver

  Everything on remote gRPC server, including the private key, no state stored on sshpiperd server.

• Database Driver

  Database upstream driver connected to popular databases, such as mysql, pg or sqlite etc to provide upstream's information.

• Kubernetes Driver

  Kubernetes drive can configure pipe with CRD.

During SSH publickey auth, RFC 4252 Section 7, ssh client sign session_id and some other data using private key into a signature sig. This is for server to verify that the connection is from the client not the man in the middle.

However, sshpiper actually holds two ssh connection, and it is doing what the man in the middle does. the two ssh connections' session_id will never be the same, because they are hash of the shared secret. RFC 4253 Section 7.2.

To support publickey auth, sshpiper will modify the sig using a private key provided by upstream driver. e.g. (id_rsa) in the workingdir/[username]/.

How this work

+------------+        +------------------------+                       
|            |        |                        |                       
|   client   |        |   SSH Piper            |                       
|   PK_X     +-------->      |                 |                       
|            |        |      v                 |                       
|            |        |   Check PK_X           |                       
+------------+        |   in authorized_keys   |                       
                      |      |                 |                       
                      |      |                 |     +----------------+
                      |      v                 |     |                |
                      |   sign agian           |     |   server       |
                      |   using PK_Y  +-------------->   check PK_Y   |
                      |                        |     |                |
                      |                        |     |                |
                      +------------------------+     +----------------+

e.g.

on client

ssh-copy-id -i PK_X test@sshpiper

on ssh piper server

ln -s ~test/.ssh/authorized_keys workingdir/test/authorized_keys
ssh-keygen -N '' -f workingdir/test/id_rsa  # this is PK_Y
ssh-copy-id -i workingdir/test/id_rsa test@server

now ssh test@sshpiper -i -i PK_X, sshpiper will send PK_Y to server instead of PK_X.

sshpiper allows you to add your own challenge before dialing to the upstream. if a client failed in this challenge, connection will be closed. however, the client has to pass the upstream server's auth in order to establish the whole connection. Additional Challenge is required, but not enough.

This is useful when you want use publickey and something like google-authenticator together.

• azdevcode

  Support Azure AD device code grant, More info

  sshpier will ask user to login using webpage

  To sign in, use a web browser to open the page https://microsoft.com/devicelogin and enter the code ****** to authenticate.
  

• authy

  Support token and onetouch from https://authy.com/

in sshd_config

AuthenticationMethods publickey,keyboard-interactive:pam

Enable 2FA PAM, for example, pam_yubico or pam_google_authenticator.

Auditor provides hook for messages transfered by SSH Piper which cloud log messages onto disks or filter some specific message on the fly.

• SSH Session logging (--auditor-driver=typescript-logger)

  When record_typescript is allowed, each piped connection would be recorded into typescript in --auditor-typescriptlogger-outputdir.

  The file format is compatible with scriptreplay(1)

  Example:

  $ ./sshpiperd daemon --auditor-driver=typescript-logger
  
  ssh [email protected] -p 2222
  ... do some commands
  exit
  
  
  $ cd workingdir/user_name
  $ ls *.timing *.typescript
  1472847798.timing 1472847798.typescript
  
  $ scriptreplay -t 1472847798.timing 1472847798.typescript # will replay the ssh session
  

SSH Piper comes with tools to list/add/remove pipes.

sshpiperd pipe -h to learn more.

MIT