Wallix projects

1   Introduction

sshproxy is an ACL-enabled authentication proxy based on the SSH2 protocol. In the version 0.5, it is able to handle shell sessions, remote command execution and scp file transfer. Port forwarding and sftp will be added in a future release.

Authentication can be done with passwords and/or public keys, both on client side and remote host side.

Sensible data (passwords and keys) is encrypted and all data can be stored in three different databases: client, acl and site. Of course, a common database can be used too, but for documentation purpose we will talk about three different databases.

Two database engines are included in v0.5, a file based backend, and a MySQL one. You can mix database types in the application, ie. use the MySQL for client and site databases, and use a plain file for the ACL database.

2   Acknowledgement

Since sshproxy version 0.5 is still in development, information in this documentation may not be accurate, and is subject to change without notice. The best documentation as of yet is the source code.

3   Getting the sources

Until 0.5 final release, you can get the sources with git or cogito:

$ cg-clone http://penguin.fr/git/sshproxy.git
$ cd sshproxy

4   Installation

Installation is as easy as typing:

# python setup.py install

5   Configuration

To configure sshproxy before a first run, you need to use the script sshproxy-setup:

$ sshproxy-setup

This will display a menu allowinging you to tweek the configuration options:

Configure sshproxy
==================

Global options
1. IP address or interface [any]
2. Port [2242]
3. Auto-add public key [no]
4. Public key id string [sshproxy@penguin.fr]
5. Cipher engine [blowfish]
6. Blowfish secret passphrase [**********]

Choose backends
7. ACL database backend type [file_db]
8. Client database backend type [file_db]
9. Site backend type [file_db]

Configure backends
10. File Backend

Plugin options
11. Select plugins


0. Quit

Please make a choice:

Default values should be OK for a first try, using the file_db backend for both three databases.

When you quit the menu, sshproxy-setup will create the necessary configuration directories and files in $HOME/.sshproxy.

The main configuration file is sshproxy.ini. Here is a sample sshproxi.ini:

[sshproxy]
bindip =
port = 2242
plugin_dir = /usr/lib/sshproxy
logger_conf = /usr/share/sshproxy/logger.conf
log_dir = @log
pkey_id = sshproxy@penguin.fr
auto_add_key = no
client_db = file_db
acl_db = file_db
site_db = file_db
plugin_list = file_db
cipher_type = blowfish

[blowfish]
secret = This should be a valid passphrase

[client_db.file]
file = @client.db

[acl_db.file]
file = @acl.db

[site_db.file]
db_path = @site.db

In this file, there are several sections. The first one, [sshproxy] is the main section, while all the other sections are provided by plugins or different optional features of the program.

The next step is to create an admin client user that will be able to create clients and sites, and edit ACL rules:

$ sshproxy-setup --add-admin admin
Enter password:
Enter password (verify):
Admin admin added.
$

Now, we're ready to start the proxy daemon sshproxyd.

6   Running the proxy

Start sshproxy by executing the following command:

$ sshproxyd
Server ready, clients may login now ...

You can make it start as a daemon with the --daemon option:

$ sshproxyd --daemon
$

7   Administering the proxy

We now have the proxy running, and an admin user has been added to the client database. We can now connect to the proxy with this admin user to add other client users and sites.

To connect to the proxy as the admin user, run the following command:

$ USER=admin pssh
sshproxy>

Or, with the normal ssh client:

$ ssh -tp 2242 admin@localhost
sshproxy>

Type help to see the list of available commands:

sshproxy> help
Documented commands (type help <topic>):
========================================
add_client   del_client  list_aclrules  message      shutdown    watch
add_site     del_site    list_clients   nb_con       tag_client
del_aclrule  kill        list_sites     set_aclrule  tag_site

sshproxy>

The commands that interest us for now are the add_*, list_* and tag_* sets of commands.

Let's start by listing clients:

sshproxy> list_clients
admin

Total: 1
sshproxy>

We now add another client:

sshproxy> add_client sasha
Client sasha added
sshproxy>

Set the password for sasha:

sshproxy> tag_client sasha password=sashapassword
username = "sasha"
password = "64fba6d2f1c7082f2e682b91492cb777804ab03e"
sshproxy>

You can set several tags at once:

sshproxy> tag_client sasha groups="web mail" ip_src="192.168.1.7"
username = "sasha"
password = "64fba6d2f1c7082f2e682b91492cb777804ab03e"
ip_src = "192.168.1.7"
groups = "web mail"
sshproxy>

Read the section ACL tags for details about tags.

Let's add a site, so that sasha will be able to log into its favorite server:

sshproxy> add_site bigtruck
Site bigtruck added
sshproxy>

Set the tags of the bigtruck server:

sshproxy> tag_site bigtruck ip_address=1.2.3.4 port=22
ip_address = "1.2.3.4"
port = "22"
name = "bigtruck"
sshproxy>

Let's add a login to the bigtruck server:

sshproxy> add_site nine@bigtruck
Site nine@bigtruck added
sshproxy> tag_site nine@bigtruck password="ninepasswd"
login = "nine"
password = "$blowfish$sFFqBatXr057vnj2g=="
name = "bigtruck"
sshproxy>

Now we need to create a special relation between the client sasha and the site login nine@bigtruck, so that sasha will be able to log into bigtruck as user nine:

sshproxy> set_aclrule sasha client.username == "sasha"
sshproxy> set_aclrule authenticate acl(sasha)
sshproxy> set_aclrule authorize acl(sasha)
sshproxy> set_aclrule shell_session site.name in split(client.sites)
sshproxy> tag_client sasha sites="bigtruck"

Read the section ACL rules for details about what we've done here.

8   Using the proxy

Once the server has been started, you can connect to the proxy either with the standard ssh client, or with the pssh wrapper.

To connect to the proxy with the standard ssh client, enter the following command:

$ ssh -tp 2242 user@sshproxy -- --help
Password:

Enter the password, hit enter, and, if you have set the ACL rules in a file like the one described in The acl.db file database format, you may see something like:

$ ssh -tp 2242 user@sshproxy -- --help
Password:
usage:
        pssh [options]
        pssh [user@site [cmd]]


options:
  -h, --help        show this help message and exit
  -l, --list-sites  list allowed sites
  --get-pssh        display pssh client script.
  --get-pscp        display pscp client script.
Connection to sshproxy closed.
$

You can see it does mention the usage of pssh. In fact pssh is the wrapper to connect to the sshproxy server. So you can do the same as with the standard ssh client in a much simpler manner:

$ export SSHPROXY_HOST='127.0.0.1'
$ export SSHPROXY_PORT='2242'
$ export SSHPROXY_USER='user'
$ pssh --help
Password:
usage:
        pssh [options]
        pssh [user@site [cmd]]


options:
  -h, --help        show this help message and exit
  -l, --list-sites  list allowed sites
  --get-pssh        display pssh client script.
  --get-pscp        display pscp client script.
Connection to sshproxy closed.
$

Note that you don't have to type the export lines every time in the same console. You can put them in your ~/.bashrc or ~/.bash_profile if you often use the pssh and pscp commands

Note also that the different options listed by --help are subject to restrictions due to ACL rules, so you may or may not see the same, depending on your ACL settings, and the loaded plugins.

A file tranfer is possible too, with the same approach. You can either use the standard scp command, or use the pscp wrapper (make sure you set the ACL rule scp_transfer to True in the ACL database):

$ scp -oPort=2242 user@sshproxy some_local_file user@proxy:root@remote:some_path/

Is the same as:

$ pscp some_local_file root@remote:some_path/

And to download a file:

$ scp -oPort=2242 user@sshproxy user@proxy:root@remote:some_path/some_remote_file .

The same with pscp:

$ pscp root@remote:some_path/some_remote_file .

9   ACL: Access Control List

authenticate:
    client.ip_addr = "192.168.1.7"

authenticate:
    client.username = "foo"

authorize:
    client.username = "foo" and site.name = "mailhost"

shell_session:
    proxy.time >= "08:00" and proxy.time <= "18:00"

authenticate:
    # anyone is allowed to authenticate on work hours,
    # but only clients from the LAN are allowed anytime
    client.ip_addr := "192.168.1." or acl(work_hours)

authorize:
    # authorize anyone anytime
    True

admin:
    # david is admin
    client.username = "david"

shell_session:
    # shell session is allowed on work hours,
    # or anytime for admin
    acl(work_hours) or acl(admin)

remote_command:
    # only free and uptime are allowed,
    # unless the user is admin
    proxy.cmdline in split("uptime free") or acl(admin)

work_hours:
    # from 09:00 to 19:00 on Monday to Friday
    proxy.time >= "09:00" and proxy.time <= "19:00"
    and proxy.dow in "12345"

authenticate: client.ip_addr == "172.30.0.1"

authorize: client.username == "johann" and client.ip_addr := "192.168.7."

# tag_client username client.groups = "monitor user"
monitors: "monitor" in split(client.groups)
console_session: acl(monitors)

# tag_client username client.hostip = "10.0.0.42"
scp_download: client.ip_addr == client.hostip

# tag_site user@sitename repository="/var/www/example.com/htdocs/download/"
scp_upload: proxy.scp_path := site.repository

opt_list_sites: True

remote_exec:
    "guest" in split(client.groups)
    and proxy.time >= "08:00" and proxy.time < "18:00"
    and proxy.cmdline == "date"

10   Backends

[david]
password = user_password
pkey =

[DEFAULT]
ip_address = 192.168.1.5
port = 22

[root]
password = $blowfish$RXX7kQrEl3g=
pkey =
priority = 1

authenticate:
    True

authorize:
    True

shell_session:
    True

[sshproxy]
... keep other values as needed ...
plugin_list = mysql_db
client_db = mysql
acl_db = mysql
site_db = mysql

[client_db.mysql]
db = sshproxy
host = localhost
user = sshproxy
password = sshproxypw
port = 3306

[acl_db.mysql]
db = sshproxy
host = localhost
user = sshproxy
password = sshproxypw
port = 3306

[site_db.mysql]
db = sshproxy
host = localhost
user = sshproxy
password = sshproxypw
port = 3306

11   Extra plugins

my_acl:
    len(split(client.groups)) > 3

my_acl:
    # client can connect every hour from HH:00 to HH:09 only
    substr(3, 4, proxy.time) == "0"

remote_exec:
    # when /var occupation is over 95%, bob can remove a big file
    client.username == "bob" and diskspace("/var") >= 950
    and proxy.cmdline == "rm -f /var/tmp/big_file"

$ pssh user@site

is equivalent to:

$ pssh
sshproxy> open user@site

$ pssh user@site cat /proc/cpuinfo

is equivalent to:

$ pssh
sshproxy> run user@site cat /proc/cpuinfo