Skip to content


Repository files navigation

sshpiper πŸ–‡

E2E Go Report Card Docker Image

sshpiper is the reverse proxy for sshd. all protocols, including ssh, scp, port forwarding, running on top of ssh are supported.

Note: this is v1 version, checkout legacy v0 here

Overview and Terminology

  • downstream: the client side, typically an ssh client.
  • upstream: the server side, typically an ssh server.
  • plugin: handles the routing from downstream to upstream. The plugin is also responsible for mapping authentication methods to the upstream server. For example, the downstream may use password authentication, but the upstream server may receive public key authentication mapped by sshpiper.
  • additional challenge: some plugins will not only perform routing but also add additional challenges to SSH authentication for the upstream server. For example, the downstream may be asked for two-factor authentication provided by the plugin.
+---------+                      +------------------+          +-----------------+
|         |                      |                  |          |                 |
|   Bob   +----ssh -l bob----+   |   sshpiper    +------------->   Bob' machine  |
|         |                  |   |               |  |          |                 |
+---------+                  |   |               |  |          +-----------------+
                             +---> pipe-by-name--+  |                             
+---------+                  |   |               |  |          +-----------------+
|         |                  |   |               |  |          |                 |
|  Alice  +----ssh -l alice--+   |               +------------->  Alice' machine |
|         |                      |                  |          |                 |
+---------+                      +------------------+          +-----------------+

 downstream                         sshpiper                        upstream                     

Quick start


git clone
cd sshpiper
git submodule update --init --recursive

mkdir out
go build -tags full -o out ./...

Run simple demo

start dummy sshd server

docker run -d -e USER_NAME=user -e USER_PASSWORD=pass -e PASSWORD_ACCESS=true -p

start sshpiperd with fixed plugin targeting the dummy sshd server

sudo ./out/sshpiperd ./out/fixed --target

test ssh connection (password: pass)

ssh -l user -p 2222

βž• math before login?

Here illustrates the example of addional challenge before the fixed plugin.

sudo ./out/sshpiperd --log-level=trace ./out/simplemath -- ./out/fixed --target



  • πŸ”€: routing plugin
  • πŸ”’: addtional challenge plugin

Plugin list

  • workingdir πŸ”€: /home-like directory to managed upstreams routing by sshpiped.
  • workingdirbykey πŸ”€: same as workingdir but uses public key to route.
  • yaml πŸ”€: config routing with a single yaml file.
  • docker πŸ”€: pipe into docker containers.
  • kubernetes πŸ”€: manage pipes via Kubernetes CRD.
  • totp πŸ”’: TOTP 2FA plugin. compatible with all RFC6238 authenticator, for example: google authenticator, azure authenticator.
  • azdevicecode πŸ”’: ask user to enter azure device code before login
  • fixed πŸ”€: fixed targeting the dummy sshd server
  • simplemath πŸ”’: ask for very simple math question before login, demo purpose
  • githubapp πŸ”€: login ssh with your github account
  • restful by @11notes πŸ”€πŸ”’: The rest plugin for sshpiperd is a simple plugin that allows you to use a restful backend for authentication and challenge.
  • failtoban πŸ”’: ban ip after failed login attempts
  • openpubkeyπŸ”€πŸ”’: integrate with openpubkey

Screening recording

sshpiperd support recording the screen in typescript format (not the lang). The format is compatible with scriptreplay(1)

To use it, start sshpiperd with --typescript-log-dir loggingdir


ssh user_name@ -p 2222
... do some commands

$ cd loggingdir/user_name
$ ls *.timing *.typescript
1472847798.timing 1472847798.typescript

$ scriptreplay -t 1472847798.timing 1472847798.typescript # will replay the ssh session

Public key authentication when using sshpiper (Private key remapping)

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 routing plugin must provide a new private key for the upstream to sign the session_id. This new private key is called mapping key.

How this work

+------------+        +------------------------+                       
|            |        |                        |                       
|   client   |        |   sshpiper             |                       
|   PK_X     +-------->      |                 |                       
|            |        |      v                 |                       
|            |        |   Check Permission     |                       
+------------+        |      |                 |                       
                      |      |                 |                       
                      |      |                 |     +----------------+
                      |      v                 |     |                |
                      |   sign agian           |     |   server       |
                      |   using PK_Y  +-------------->   check PK_Y   |
                      |                        |     |                |
                      |                        |     |                |
                      +------------------------+     +----------------+

Migrating from v0

What's the major change in v1

  • low level sshpiper api is fully redesigned to support more routing protocols.
  • plugins system totally redesigned to be more flexible and extensible.
    • plugins are now sperated from main process and no longer a single big binary, this allow user to write their own plugins without touching sshpiperd code.
  • grpc is first class now, the plugins are built on top of it

For plugins already in v1, you need change params to new params. However, not all plugins are migrated to v1 yet, they are being migrated gradually. you can still use the old plugins in v0 branch