==== vssh

:Author: Stéphane Martin

.. contents:: :depth: 1 ..

.. section-numbering::

introduction

vssh is a SSH client that uses Hashicorp's vault to authenticate with SSH certificates.

How it works:

• first of all you need to configure the SSH certificate authority in Vault (see Vault documentation <https://www.vaultproject.io/docs/secrets/ssh/signed-ssh-certificates.html>_)

  • inject the CA private and public keys into Vault
  • configure the target OpenSSH servers to accept keys signed by the CA

• just as with an usual SSH client, specify to vssh

  • which server you want to connect to
  • witch which remote user
  • witch private key to use

• say how to to connect to Vault

  • Vault address
  • Vault authentication (token, login/password, ...)

• say which SSH signing role to use in Vault

vssh will then

• submit your SSH private key to vault for signing
• fetch the signed SSH certificate from vault
• use the private key and the certificate to authenticate and connect to the remote SSH server

vssh can open an interactive shell on the remote server, or execute a command.

install

Nothing special. Just copy the binary into your PATH.

compile

The dependencies are vondored using dep <https://golang.github.io/dep/>_. You do not need it to compile vssh. Just clone in an appropriate directoty (GOROOT) and run make release.

.. code-block:: bash

mdkir -p ~/go/src/github.com/stephane-martin cd ~/go/src/github.com/stephane-martin git clone https://github.com/stephane-martin/vssh cd vssh make release

develop

• Clone the repository in an appropriate go directory.
• Install dep <https://golang.github.io/dep/>_ and golangci-lint <https://github.com/golangci/golangci-lint>_.
• Compile with make debug and lint with make lint.

usage

vssh can open an interactive SSH session (vssh ssh), execute a remote command (vssh ssh), and download (vssh download) / upload (vssh upload) files using the scp protocol.

Most of command line options can be specified with environnemt variables instead. Check vssh --help for details.

global options

The global options are useful for the different vssh commands. They configure the connection to Vault.

+-----------------------+--------------------------------+----------------------------------------------------------------+ | Global option | Value Example | Definition | +-----------------------+--------------------------------+----------------------------------------------------------------+ | --vault-addr | http://127.0.0.1:8200 | vault connection URL | +-----------------------+--------------------------------+----------------------------------------------------------------+ | --vault-method | userpass | vault authentication method [token, userpass, ldap, approle] | +-----------------------+--------------------------------+----------------------------------------------------------------+ | --vault-username | myvaultuser | username for vault authentication | +-----------------------+--------------------------------+----------------------------------------------------------------+ | --vault-password | myvaultpass | password for vault authentication | +-----------------------+--------------------------------+----------------------------------------------------------------+ | --vault-ssh-role | myrole | name of the SSH sign role you have configured in Vault | +-----------------------+--------------------------------+----------------------------------------------------------------+ | --vault-token | s.lIz3muuaUOZe424j2ZI5GTDK | token for vault authentication | +-----------------------+--------------------------------+----------------------------------------------------------------+ | --vault-ssh-mount | ssh-client-signer | the path to the SSH signer in Vault | +-----------------------+--------------------------------+----------------------------------------------------------------+ | --vault-auth-path | custompath | if the Vault authentication method is mounted to a custom path | +-----------------------+--------------------------------+----------------------------------------------------------------+

interactive SSH session

.. code-block:: bash

vssh [global options] ssh [ssh options] user@host

vssh ssh --help

vssh needs a private key to send to Vault for signature. You can give it:

• a private key that is stored locally on your filesystem with --identity
• or a private key stored in vault with --videntity

vssh will ask for a passphrase if the private key is stored in encrypted form.

+-----------------+----------------------------+---------------------------------------------------------+ | SSH option | Value Example | Definition | +-----------------+----------------------------+---------------------------------------------------------+ | --identity | /path/to/id_rsa | file path to the SSH private key that should be signed | +-----------------+----------------------------+---------------------------------------------------------+ | --videntity | secret/id_rsa_in_vault | Vault path to the SSH private key that should be signed | +-----------------+----------------------------+---------------------------------------------------------+ | --insecure | | do not check the SSH server host key | +-----------------+----------------------------+---------------------------------------------------------+ | --native | | use the local ssh binary to make the connection | +-----------------+----------------------------+---------------------------------------------------------+ | --terminal | | force pseudo-terminal allocation | +-----------------+----------------------------+---------------------------------------------------------+ | --ssh-port | 22 | SSH server listen port | +-----------------+----------------------------+---------------------------------------------------------+ | --login | admin | alternate way to specify the remote user | +-----------------+----------------------------+---------------------------------------------------------+

remote command

.. code-block:: bash

vssh [global options] ssh [ssh options] user@host command

vssh [global options] ssh -t [ssh options] user@host command

Just put the command the execute at the end of the vssh ssh command line.

If the command is meant to be interactive, then you need to add the -t flag. For example, to launch an alternate shell:

.. code-block:: bash

vssh ssh -t me@remote zsh

It is also possible to inject some Vault secrets into the remote command environment, similarly to --envconsul, with the following flags:

+----------------+-------------------+------------------------------------------------------------+ | SSH option | Value Example | Definition | +----------------+-------------------+------------------------------------------------------------+ | --secret | secret/path | path of a secret to read from Vault | +----------------+-------------------+------------------------------------------------------------+ | --upcase | | convert environment variable keys to UPPERCASE | +----------------+-------------------+------------------------------------------------------------+ | --prefix | | prefix the environment variable keys with names of secrets | +----------------+-------------------+------------------------------------------------------------+

download

.. code-block:: bash

vssh [global options] download [download options] --target file1 [--target file2...] user@host

vssh download --help

Specify the remote files/directories you want to download with the --target flag. It can appear multiple times.

Specify the local destination path with the --destination flag.

The other flags are similar to the vssh ssh command.

+---------------------+----------------------------+---------------------------------------------------------+ | download option | Value Example | Definition | +---------------------+----------------------------+---------------------------------------------------------+ | --identity | /path/to/id_rsa | file path to the SSH private key that should be signed | +---------------------+----------------------------+---------------------------------------------------------+ | --videntity | secret/id_rsa_in_vault | Vault path to the SSH private key that should be signed | +---------------------+----------------------------+---------------------------------------------------------+ | --insecure | | do not check the SSH server host key | +---------------------+----------------------------+---------------------------------------------------------+ | --target | remotefile | path to the remote file to be downloaded | +---------------------+----------------------------+---------------------------------------------------------+ | --destination | /tmp | local destination path | +---------------------+----------------------------+---------------------------------------------------------+ | --ssh-port | 22 | SSH server listen port | +---------------------+----------------------------+---------------------------------------------------------+ | --login | admin | alternate way to specify the remote user | +---------------------+----------------------------+---------------------------------------------------------+ | --preserve | | preserve file mode, access time and modification time | +---------------------+----------------------------+---------------------------------------------------------+

upload

.. code-block:: bash

vssh [global options] upload [upload options] user@host

vssh upload --help

Specify the local files/directories you want to upload with the --source flag. It can appear multiple times.

Specify the remote destination path with the --destination flag.

The other flags are similar to the vssh ssh command.

+---------------------+----------------------------+---------------------------------------------------------+ | download option | Value Example | Definition | +---------------------+----------------------------+---------------------------------------------------------+ | --identity | /path/to/id_rsa | file path to the SSH private key that should be signed | +---------------------+----------------------------+---------------------------------------------------------+ | --videntity | secret/id_rsa_in_vault | Vault path to the SSH private key that should be signed | +---------------------+----------------------------+---------------------------------------------------------+ | --insecure | | do not check the SSH server host key | +---------------------+----------------------------+---------------------------------------------------------+ | --source | localfile | path to the local file to be uploaded | +---------------------+----------------------------+---------------------------------------------------------+ | --destination | /tmp | remote destination path | +---------------------+----------------------------+---------------------------------------------------------+ | --ssh-port | 22 | SSH server listen port | +---------------------+----------------------------+---------------------------------------------------------+ | --login | admin | alternate way to specify the remote user | +---------------------+----------------------------+---------------------------------------------------------+

as a library

TODO

examples

Let's assume you have configured a few environment variables, to avoid repetition in the examples.

.. code-block:: bash

export VAULT_ADDR=https://vault.example.org:8200 export VAULT_SSH_MOUNT=ssh-client-signer export VAULT_SIGNING_ROLE=my-vault-ssh-role

With such variables, vssh knowns:

• how to connect to the Vault server instance
• which certificate authority to use in Vault
• which SSH role to use in Vault to produce the certificates

Let's also assume you have generated a SSH private key for your local current user::

ssh-keygen

single sign on

Open a terminal, then authenticate yourself with Vault:

.. code-block:: bash

vault login -method=userpass username=bob

The vault login command writes the resulting token in ~/.vault_token. If you don't specify to vssh how to authenticate to Vault, by default it will use that token.

You can then SSH to any server that recognizes the Vault CA:

.. code-block:: bash

vssh ssh me@myserver.example.org

execute a remote command

.. code-block:: bash

vssh ssh me@myserver.example.org ls -al /

execute a remote command in a pseudo-terminal

.. code-block:: bash

vssh ssh -t me@myserver.example.org zsh

inject Vault secrets in the remote session

Now let's say you want to execute a remote command on a server, but some part of the configuration for that command is stored in Vault.

vssh can work similar to envconsul:

.. code-block:: bash

vssh ssh --secret secret/mysecret me@myserver.example.org backupcommand

Locally, vssh will read the required secret from Vault. Then it opens the SSH connection. Then the command will be executed, with environment variables corresponding to the secrets.

So, if secret/mysecret is something like::

foo=bar ZOG=ZOG

then vssh executes on the remote SSH server:

.. code-block:: bash

env foo=bar ZOG=ZOG backupcommand

with the additional --upcase flag, it becomes:

.. code-block:: bash

env FOO=bar ZOG=ZOG backupcommand

or with the additional --prefix flag it becomes:

.. code-block:: bash

env secret_mysecret_foo=bar secret_mysecret_ZOG=ZOG backupcommand

Your remote SSH environment doesn't have to know anything about Vault by itself.

questions

what does the --native flag do ?

By default vssh uses an internal SSH client implemented in Go.

• Go implementation, so vssh does not need to launch another process.
• Might behave differently compared to the native ssh command.
• Does not read .ssh/config.
• The signed certificate is not written to the filesystem, it is passed directly to the SSH client in memory.

With --native, vssh wraps the native ssh binary. It can be useful it you wish to enable the native configuration of the SSH client (man 5 ssh_config).

• there vssh launches a SSH subprocess
• the SSH subprocess will read ssh_config as usual
• to pass the signed certificate to SSH, vssh has to write it to the filesystem (it will be removed at the end of execution)

what should be the TTL for signed certificates ?

Very short. After Vault has signed the SSH certificate, vssh uses that certificate immediatly and only once. Every time vssh is executed, another certificate will be created. So in theory, a TTL of a few seconds is just enough.