From 2b8f051414cdbf4de00a65cd48f65088b83dc39e Mon Sep 17 00:00:00 2001 From: Nelly Asher Date: Thu, 31 Jan 2019 22:02:48 +0200 Subject: [PATCH 1/3] TOC added, chapters rearranged, "Use cases" added. --- README.md | 341 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 198 insertions(+), 143 deletions(-) diff --git a/README.md b/README.md index 6391d248..e5594572 100644 --- a/README.md +++ b/README.md @@ -9,56 +9,31 @@ Jump host/Jump server without the jump, a.k.a Transparent SSH bastion -![sshportal demo](https://github.com/moul/sshportal/raw/master/.assets/demo.gif) - ---- - -## Overview - -![sshportal overview](https://raw.github.com/moul/sshportal/master/.assets/overview.png) +Features include: independence of users and hosts, convenient user invite system, connecting to servers that don't support SSH keys, various levels of access, and many more. Easy to install, run and configure. -## Features +[![FLOW DIAGRAM - PLEASE UPLOAD TO YOUR .assets FOLDER]() -* 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](https://www.sqlite.org/) or [MySQL](https://www.mysql.com) (probably easy to add postgres, mssql thanks to gorm) -* Stateless -> horizontally scalable when using [MySQL](https://www.mysql.com) 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`](https://linux.die.net/man/1/scp) support - * [`rsync`](https://linux.die.net/man/1/rsync) support - * [tunneling](https://www.ssh.com/ssh/tunneling/example) (local forward, remote forward, dynamic forward) support - * [`sftp`](https://www.ssh.com/ssh/sftp/) support - * [`ssh-agent`](https://www.ssh.com/ssh/agent) support - * [`X11 forwarding`](http://en.tldp.org/HOWTO/XDMCP-HOWTO/ssh.html) 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 - * [Telnet](https://www.ssh.com/ssh/telnet) support +--- -## (Known) limitations +## Contents + +1. Installation and usage. +2. Use cases. +3. Features and limitations. +4. Running with Docker. +5. Manual Install +6. Backup/Restore. +7. Built-in shell. +8. Demo data. +9. Shell commands. +10. Healthcheck. +11. portal alias (.ssh/config) +12. Scaling +13. Under the hood -* Does not work (yet?) with [`mosh`](https://mosh.org/) +--- -## Usage +## Installation and usage Start the server @@ -138,96 +113,69 @@ To associate this account with a key, use the following SSH user: 'invite:NfHK5a config> ``` -## Flow Diagram - -![Flow Diagram](https://raw.github.com/moul/sshportal/master/.assets/flow-diagram.png) - -## built-in shell - -`sshportal` embeds a configuration CLI. - -By default, the configuration user is `admin`, (can be changed using `--config-user=` when starting the server. +Demo gif: +![sshportal demo](https://github.com/moul/sshportal/raw/master/.assets/demo.gif) -Each commands can be run directly by using this syntax: `ssh admin@portal.example.org [args]`: +--- -``` -ssh admin@portal.example.org host inspect toto -``` +## Use cases -You can enter in interactive mode using this syntax: `ssh admin@portal.example.org` +Used by educators to provide temporary access to students. [Feedback from a teacher](https://github.com/moul/sshportal/issues/64). The author is using it in one of his projects, *pathwar*, to dynamically configure hosts and users, so that he can give temporary accesses for educational purposes. -### Synopsis +*vptech*, the vente-privee.com technical team (a group of over 6000 people) is using it internally to manage access to servers/routers, saving hours on configuration management and not having to share the configuration information. -```sh -# acl management -acl help -acl create [-h] [--hostgroup=HOSTGROUP...] [--usergroup=USERGROUP...] [--pattern=] [--comment=] [--action=] [--weight=value] -acl inspect [-h] ACL... -acl ls [-h] [--latest] [--quiet] -acl rm [-h] ACL... -acl update [-h] [--comment=] [--action=] [--weight=] [--assign-hostgroup=HOSTGROUP...] [--unassign-hostgroup=HOSTGROUP...] [--assign-usergroup=USERGROUP...] [--unassign-usergroup=USERGROUP...] ACL... +There are companies who use a jump host to monitor connections at a single point. -# config management -config help -config backup [-h] [--indent] [--decrypt] -config restore [-h] [--confirm] [--decrypt] +A hosting company is using SSHportal for its “logging” feature, among the others. As every session is logged and introspectable, they have a detailed history of who performed which action. This company made its own contribution on the project, allowing the support of [more than 65.000 sessions in the database](https://github.com/moul/sshportal/pull/76). -# event management -event help -event ls [-h] [--latest] [--quiet] -event inspect [-h] EVENT... +The project has also received [multiple contributions from a security researcher](https://github.com/moul/sshportal/pulls?q=is%3Apr+author%3Asabban+sort%3Aupdated-desc) that made a thesis on quantum cryptography. This person uses SSHportal in their security-hardened hosting company. -# host management -host help -host create [-h] [--name=] [--password=] [--comment=] [--key=KEY] [--group=HOSTGROUP...] [--hop=HOST] [:]@[:] -host inspect [-h] [--decrypt] HOST... -host ls [-h] [--latest] [--quiet] -host rm [-h] HOST... -host update [-h] [--name=] [--comment=] [--key=KEY] [--assign-group=HOSTGROUP...] [--unassign-group=HOSTGROUP...] [--set-hop=HOST] [--unset-hop] HOST... +If you need to invite multiple people to an event (hackathon, course, etc), the day before the event you can create multiple accounts at once, print the invite, and distribute the paper. -# hostgroup management -hostgroup help -hostgroup create [-h] [--name=] [--comment=] -hostgroup inspect [-h] HOSTGROUP... -hostgroup ls [-h] [--latest] [--quiet] -hostgroup rm [-h] HOSTGROUP... +--- -# key management -key help -key create [-h] [--name=] [--type=] [--length=] [--comment=] -key import [-h] [--name=] [--comment=] -key inspect [-h] [--decrypt] KEY... -key ls [-h] [--latest] [--quiet] -key rm [-h] KEY... -key setup [-h] KEY -key show [-h] KEY +## Features and limitations -# session management -session help -session ls [-h] [--latest] [--quiet] -session inspect [-h] SESSION... +* 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](https://www.sqlite.org/) or [MySQL](https://www.mysql.com) (probably easy to add postgres, mssql thanks to gorm) +* Stateless -> horizontally scalable when using [MySQL](https://www.mysql.com) 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`](https://linux.die.net/man/1/scp) support + * [`rsync`](https://linux.die.net/man/1/rsync) support + * [tunneling](https://www.ssh.com/ssh/tunneling/example) (local forward, remote forward, dynamic forward) support + * [`sftp`](https://www.ssh.com/ssh/sftp/) support + * [`ssh-agent`](https://www.ssh.com/ssh/agent) support + * [`X11 forwarding`](http://en.tldp.org/HOWTO/XDMCP-HOWTO/ssh.html) 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 + * [Telnet](https://www.ssh.com/ssh/telnet) support -# user management -user help -user invite [-h] [--name=] [--comment=] [--group=USERGROUP...] -user inspect [-h] USER... -user ls [-h] [--latest] [--quiet] -user rm [-h] USER... -user update [-h] [--name=] [--email=] [--set-admin] [--unset-admin] [--assign-group=USERGROUP...] [--unassign-group=USERGROUP...] USER... +**(Known) limitations** -# usergroup management -usergroup help -hostgroup create [-h] [--name=] [--comment=] -usergroup inspect [-h] USERGROUP... -usergroup ls [-h] [--latest] [--quiet] -usergroup rm [-h] USERGROUP... +* Does not work (yet?) with [`mosh`](https://mosh.org/) -# other -exit [-h] -help, h -info [-h] -version [-h] -``` +--- ## Docker @@ -273,6 +221,8 @@ docker start sshportal docker logs -f sshportal ``` +--- + ## Manual Install Get the latest version using GO. @@ -281,28 +231,7 @@ Get the latest version using GO. go get -u moul.io/sshportal ``` -## portal alias (.ssh/config) - -Edit your `~/.ssh/config` file (create it first if needed) - -```ini -Host portal - User admin - Port 2222 # portal port - HostName 127.0.0.1 # portal hostname -``` - -```bash -# 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 @@ -328,6 +257,26 @@ sqlite3 sshportal.db .dump > sshportal.sql.bkp cp sshportal.db sshportal.db.bkp ``` +--- + +## built-in shell + +`sshportal` embeds a configuration CLI. + +By default, the configuration user is `admin`, (can be changed using `--config-user=` when starting the server. + +Each commands can be run directly by using this syntax: `ssh admin@portal.example.org [args]`: + +``` +ssh admin@portal.example.org host inspect toto +``` + +You can enter in interactive mode using this syntax: `ssh admin@portal.example.org` + +![sshportal overview](https://raw.github.com/moul/sshportal/master/.assets/overview.svg?sanitize=true) + +--- + ## Demo data The following servers are freely available, without external registration, @@ -344,6 +293,83 @@ ssh portal host create test@chat.shazow.net ssh chat@portal ``` +--- + +## Shell commands + +```sh +# acl management +acl help +acl create [-h] [--hostgroup=HOSTGROUP...] [--usergroup=USERGROUP...] [--pattern=] [--comment=] [--action=] [--weight=value] +acl inspect [-h] ACL... +acl ls [-h] [--latest] [--quiet] +acl rm [-h] ACL... +acl update [-h] [--comment=] [--action=] [--weight=] [--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=] [--password=] [--comment=] [--key=KEY] [--group=HOSTGROUP...] [--hop=HOST] [:]@[:] +host inspect [-h] [--decrypt] HOST... +host ls [-h] [--latest] [--quiet] +host rm [-h] HOST... +host update [-h] [--name=] [--comment=] [--key=KEY] [--assign-group=HOSTGROUP...] [--unassign-group=HOSTGROUP...] [--set-hop=HOST] [--unset-hop] HOST... + +# hostgroup management +hostgroup help +hostgroup create [-h] [--name=] [--comment=] +hostgroup inspect [-h] HOSTGROUP... +hostgroup ls [-h] [--latest] [--quiet] +hostgroup rm [-h] HOSTGROUP... + +# key management +key help +key create [-h] [--name=] [--type=] [--length=] [--comment=] +key import [-h] [--name=] [--comment=] +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=] [--comment=] [--group=USERGROUP...] +user inspect [-h] USER... +user ls [-h] [--latest] [--quiet] +user rm [-h] USER... +user update [-h] [--name=] [--email=] [--set-admin] [--unset-admin] [--assign-group=USERGROUP...] [--unassign-group=USERGROUP...] USER... + +# usergroup management +usergroup help +hostgroup create [-h] [--name=] [--comment=] +usergroup inspect [-h] USERGROUP... +usergroup ls [-h] [--latest] [--quiet] +usergroup rm [-h] USERGROUP... + +# other +exit [-h] +help, h +info [-h] +version [-h] +``` + +--- + ## Healthcheck By default, `sshportal` will return `OK` to anyone sshing using the `healthcheck` user without checking for authentication. @@ -376,6 +402,33 @@ $ sshportal healthcheck --wait && ssh sshportal -l admin config> ``` +--- + +## portal alias (.ssh/config) + +Edit your `~/.ssh/config` file (create it first if needed) + +```ini +Host portal + User admin + Port 2222 # portal port + HostName 127.0.0.1 # portal hostname +``` + +```bash +# 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 +``` + +--- + ## Scaling `sshportal` is stateless but relies on a database to store configuration and logs. @@ -388,6 +441,8 @@ You can run multiple instances of `sshportal` sharing a same [MySQL](https://www See [examples/mysql](http://github.com/moul/sshportal/tree/master/examples/mysql). +--- + ## Under the hood * Docker first (used in dev, tests, by the CI and in production) From 7c4995fa4ae7aa33ffac5cd34d3315513edd9f61 Mon Sep 17 00:00:00 2001 From: Nelly Asher Date: Fri, 1 Feb 2019 14:27:01 +0200 Subject: [PATCH 2/3] Update README.md --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index e5594572..7ad9a2cd 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,7 @@ Jump host/Jump server without the jump, a.k.a Transparent SSH bastion Features include: independence of users and hosts, convenient user invite system, connecting to servers that don't support SSH keys, various levels of access, and many more. Easy to install, run and configure. -[![FLOW DIAGRAM - PLEASE UPLOAD TO YOUR .assets FOLDER]() +[![Flow Diagram](https://raw.githubusercontent.com/moul/sshportal/master/.assets/flow-diagram.png) --- From 3dccefbbcbc188d4ae4c793b1e25efdcd74b4e65 Mon Sep 17 00:00:00 2001 From: Manfred Touron Date: Fri, 1 Feb 2019 13:36:36 +0100 Subject: [PATCH 3/3] chore: use png + add toc --- README.md | 34 +++++++++++++++++++--------------- 1 file changed, 19 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 7ad9a2cd..940160dc 100644 --- a/README.md +++ b/README.md @@ -11,25 +11,29 @@ Jump host/Jump server without the jump, a.k.a Transparent SSH bastion Features include: independence of users and hosts, convenient user invite system, connecting to servers that don't support SSH keys, various levels of access, and many more. Easy to install, run and configure. -[![Flow Diagram](https://raw.githubusercontent.com/moul/sshportal/master/.assets/flow-diagram.png) +![Flow Diagram](https://raw.githubusercontent.com/moul/sshportal/master/.assets/flow-diagram.png) --- ## Contents -1. Installation and usage. -2. Use cases. -3. Features and limitations. -4. Running with Docker. -5. Manual Install -6. Backup/Restore. -7. Built-in shell. -8. Demo data. -9. Shell commands. -10. Healthcheck. -11. portal alias (.ssh/config) -12. Scaling -13. Under the hood + + +- [Installation and usage](#installation-and-usage) +- [Use cases](#use-cases) +- [Features and limitations](#features-and-limitations) +- [Docker](#docker) +- [Manual Install](#manual-install) +- [Backup / Restore](#backup--restore) +- [built-in shell](#built-in-shell) +- [Demo data](#demo-data) +- [Shell commands](#shell-commands) +- [Healthcheck](#healthcheck) +- [portal alias (.ssh/config)](#portal-alias-sshconfig) +- [Scaling](#scaling) +- [Under the hood](#under-the-hood) + + --- @@ -273,7 +277,7 @@ ssh admin@portal.example.org host inspect toto You can enter in interactive mode using this syntax: `ssh admin@portal.example.org` -![sshportal overview](https://raw.github.com/moul/sshportal/master/.assets/overview.svg?sanitize=true) +![sshportal overview](https://raw.github.com/moul/sshportal/master/.assets/overview.png) ---