🎩 simple, fun and transparent SSH (and telnet) bastion
Clone or download
Latest commit 41eeb36 Aug 19, 2018
Failed to load latest commit information.
.assets Update graphs Jan 2, 2018
.circleci Run integration tests in parallel in CI Jan 1, 2018
.github Fix typo in template Feb 2, 2018
examples Ignore some circle CI tests Aug 18, 2018
pkg fix merge Apr 2, 2018
vendor Add log for exec request. Apr 2, 2018
.dockerignore Update .dockerignore Dec 17, 2017
.gitignore Ingore /log directory Feb 28, 2018
CHANGELOG.md Post-release version bump Apr 2, 2018
Dockerfile Add healthcheck --wait and --quiet options Jan 1, 2018
LICENSE Create LICENSE Dec 4, 2017
Makefile Fix 'make dev' rule Feb 28, 2018
README.md v1.8.0 Apr 2, 2018
acl.go main: remove globalContext, and move some functions outside of the main Jan 7, 2018
acl_test.go Lint code + fix tests Dec 3, 2017
config.go main: remove globalContext, and move some functions outside of the main Jan 7, 2018
crypto.go Added ssh key import feature in "key import" Mar 21, 2018
db.go Implement proxied connections Feb 22, 2018
dbinit.go Implement proxied connections Feb 22, 2018
healthcheck.go main: remove globalContext, and move some functions outside of the main Jan 7, 2018
hidden.go main: remove globalContext, and move some functions outside of the main Jan 7, 2018
main.go Post-release version bump Apr 2, 2018
shell.go Added `hostgroup update` and `usergroup update` features Apr 5, 2018
ssh.go add an acceptable error management. Mar 19, 2018
telnet.go main: remove globalContext, and move some functions outside of the main Jan 7, 2018
util.go Lint code + fix tests Dec 3, 2017



CircleCI Docker Build Status Go Report Card GoDoc License GitHub release FOSSA Status

Jump host/Jump server without the jump, a.k.a Transparent SSH bastion

sshportal demo


sshportal overview


  • Single autonomous binary (~10-20Mb) with no runtime dependencies (embeds ssh server and client)
  • Portable / Cross-platform (regularly tested on linux and OSX/darwin)
  • Store data in Sqlite3 or MySQL (probably easy to add postgres, mssql thanks to gorm)
  • Stateless -> horizontally scalable when using MySQL as the backend
  • Connect to remote host using key or password
  • Admin commands can be run directly or in an interactive shell
  • Host management
  • User management (invite, group, stats)
  • Host Key management (create, remove, update, import)
  • Automatic remote host key learning
  • User Key management (multile keys per user)
  • ACL management (acl+user-groups+host-groups)
  • User roles (admin, trusted, standard, ...)
  • User invitations (no more "give me your public ssh key please")
  • Easy server installation (generate shell command to setup authorized_keys)
  • Sensitive data encryption
  • Session management (see active connections, history, stats, stop)
  • Audit log (logging every user action)
  • Record TTY Session
  • Tunnels logging
  • Host Keys verifications shared across users
  • Healthcheck user (replying OK to any user)
  • SSH compatibility
    • ipv4 and ipv6 support
    • scp support
    • rsync support
    • tunneling (local forward, remote forward, dynamic forward) support
    • sftp support
    • ssh-agent support
    • X11 forwarding support
    • Git support (can be used to easily use multiple user keys on GitHub, or access your own firewalled gitlab server)
    • Do not require any SSH client modification or custom .ssh/config, works with every tested SSH programming libraries and every tested SSH clients
  • SSH to non-SSH proxy

(Known) limitations

  • Does not work (yet?) with mosh


Start the server

$ sshportal server
2017/11/13 10:58:35 Admin user created, use the user 'invite:BpLnfgDsc2WD8F2q' to associate a public key with this account
2017/11/13 10:58:35 SSH Server accepting connections on :2222

Link your SSH key with the admin account

$ ssh localhost -p 2222 -l invite:BpLnfgDsc2WD8F2q
Welcome admin!

Your key is now associated with the user "admin@sshportal".
Shared connection to localhost closed.

Drop an interactive administrator shell

ssh localhost -p 2222 -l admin

    __________ _____           __       __
   / __/ __/ // / _ \___  ____/ /____ _/ /
  _\ \_\ \/ _  / ___/ _ \/ __/ __/ _ '/ /
 /___/___/_//_/_/   \___/_/  \__/\_,_/_/


Create your first host

config> host create bart@foo.example.org

List hosts

config> host ls
  ID | NAME |           URL           |   KEY   | PASS | GROUPS  | COMMENT
   1 | foo  | bart@foo.example.org:22 | default |      | default |
Total: 1 hosts.

Add the key to the server

$ ssh bart@foo.example.org "$(ssh localhost -p 2222 -l admin key setup default)"


ssh localhost -p 2222 -l foo

Invite friends

This command doesn't create a user on the remote server, it only creates an account in the sshportal database.

config> user invite bob@example.com
User 2 created.
To associate this account with a key, use the following SSH user: 'invite:NfHK5a84jjJkwzDk'.

Flow Diagram

Flow Diagram

built-in shell

sshportal embeds a configuration CLI.

By default, the configuration user is admin, (can be changed using --config-user=<value> when starting the server.

Each commands can be run directly by using this syntax: ssh admin@portal.example.org <command> [args]:

ssh admin@portal.example.org host inspect toto

You can enter in interactive mode using this syntax: ssh admin@portal.example.org


# acl management
acl help
acl create [-h] [--hostgroup=HOSTGROUP...] [--usergroup=USERGROUP...] [--pattern=<value>] [--comment=<value>] [--action=<value>] [--weight=value]
acl inspect [-h] ACL...
acl ls [-h] [--latest] [--quiet]
acl rm [-h] ACL...
acl update [-h] [--comment=<value>] [--action=<value>] [--weight=<value>] [--assign-hostgroup=HOSTGROUP...] [--unassign-hostgroup=HOSTGROUP...] [--assign-usergroup=USERGROUP...] [--unassign-usergroup=USERGROUP...] ACL...

# config management
config help
config backup [-h] [--indent] [--decrypt]
config restore [-h] [--confirm] [--decrypt]

# event management
event help
event ls [-h] [--latest] [--quiet]
event inspect [-h] EVENT...

# host management
host help
host create [-h] [--name=<value>] [--password=<value>] [--comment=<value>] [--key=KEY] [--group=HOSTGROUP...] [--hop=HOST] <username>[:<password>]@<host>[:<port>]
host inspect [-h] [--decrypt] HOST...
host ls [-h] [--latest] [--quiet]
host rm [-h] HOST...
host update [-h] [--name=<value>] [--comment=<value>] [--key=KEY] [--assign-group=HOSTGROUP...] [--unassign-group=HOSTGROUP...] [--set-hop=HOST] [--unset-hop] HOST...

# hostgroup management
hostgroup help
hostgroup create [-h] [--name=<value>] [--comment=<value>]
hostgroup inspect [-h] HOSTGROUP...
hostgroup ls [-h] [--latest] [--quiet]
hostgroup rm [-h] HOSTGROUP...

# key management
key help
key create [-h] [--name=<value>] [--type=<value>] [--length=<value>] [--comment=<value>]
key import [-h] [--name=<value>] [--comment=<value>]
key inspect [-h] [--decrypt] KEY...
key ls [-h] [--latest] [--quiet]
key rm [-h] KEY...
key setup [-h] KEY
key show [-h] KEY

# session management
session help
session ls [-h] [--latest] [--quiet]
session inspect [-h] SESSION...

# user management
user help
user invite [-h] [--name=<value>] [--comment=<value>] [--group=USERGROUP...] <email>
user inspect [-h] USER...
user ls [-h] [--latest] [--quiet]
user rm [-h] USER...
user update [-h] [--name=<value>] [--email=<value>] [--set-admin] [--unset-admin] [--assign-group=USERGROUP...] [--unassign-group=USERGROUP...] USER...

# usergroup management
usergroup help
hostgroup create [-h] [--name=<value>] [--comment=<value>]
usergroup inspect [-h] USERGROUP...
usergroup ls [-h] [--latest] [--quiet]
usergroup rm [-h] USERGROUP...

# other
exit [-h]
help, h
info [-h]
version [-h]


Docker is the recommended way to run sshportal.

An automated build is setup on the Docker Hub.

# Start a server in background
#   mount `pwd` to persist the sqlite database file
docker run -p 2222:2222 -d --name=sshportal -v "$(pwd):$(pwd)" -w "$(pwd)" moul/sshportal:v1.8.0

# check logs (mandatory on first run to get the administrator invite token)
docker logs -f sshportal

The easier way to upgrade sshportal is to do the following:

# we consider you were using an old version and you want to use the new version v1.8.0

# stop and rename the last working container + backup the database
docker stop sshportal
docker rename sshportal sshportal_old
cp sshportal.db sshportal.db.bkp

# run the new version
docker run -p 2222:2222 -d --name=sshportal -v "$(pwd):$(pwd)" -w "$(pwd)" moul/sshportal:v1.8.0
# check the logs for migration or cross-version incompabitility errors
docker logs -f sshportal

Now you can test ssh-ing to sshportal to check if everything looks OK.

In case of problem, you can rollback to the latest working version with the latest working backup, using:

docker stop sshportal
docker rm sshportal
cp sshportal.db.bkp sshportal.db
docker rename sshportal_old sshportal
docker start sshportal
docker logs -f sshportal

Manual Install

Get the latest version using GO.

go get -u github.com/moul/sshportal

portal alias (.ssh/config)

Edit your ~/.ssh/config file (create it first if needed)

Host portal
  User      admin
  Port      2222       # portal port
  HostName  # portal hostname
# you can now run a shell using this:
ssh portal
# instead of this:
ssh localhost -p 2222 -l admin

# or connect to hosts using this:
ssh hostname@portal
# instead of this:
ssh localhost -p 2222 -l hostname

Backup / Restore

sshportal embeds built-in backup/restore methods which basically import/export JSON objects:

# Backup
ssh portal config backup  > sshportal.bkp

# Restore
ssh portal config restore < sshportal.bkp

This method is particularly useful as it should be resistant against future DB schema changes (expected during development phase).

I suggest you to be careful during this development phase, and use an additional backup method, for example:

# sqlite dump
sqlite3 sshportal.db .dump > sshportal.sql.bkp

# or just the immortal cp
cp sshportal.db sshportal.db.bkp

Demo data

The following servers are freely available, without external registration, it makes it easier to quickly test sshportal without configuring your own servers to accept sshportal connections.

ssh portal host create new@sdf.org
ssh sdf@portal

ssh portal host create test@whoami.filippo.io
ssh whoami@portal

ssh portal host create test@chat.shazow.net
ssh chat@portal


By default, sshportal will return OK to anyone sshing using the healthcheck user without checking for authentication.

$ ssh healthcheck@sshportal

the healtcheck user can be changed using the healthcheck-user option.

Alternatively, you can run the built-in healthcheck helper (requiring no ssh client nor ssh key):

Usage: `sshportal healthcheck [--addr=host:port] [--wait] [--quiet]

$ sshportal healthcheck --addr=localhost:2222; echo $?
$ 0

Wait for sshportal to be healthy, then connect

$ sshportal healthcheck --wait && ssh sshportal -l admin


sshportal is stateless but relies on a database to store configuration and logs.

By default, sshportal uses a local sqlite database which isn't scalable by design.

You can run multiple instances of sshportal sharing a same MySQL database, using sshportal --db-conn=user:pass@host/dbname?parseTime=true --db-driver=mysql.

sshportal cluster with MySQL backend

See examples/mysql.

Under the hood

sshportal data model


This is totally experimental for now, so please file issues to let me know what you think about it!


FOSSA Status