/vssh

SSH client using certificates signed by hashicorp's vault

Primary LanguageGoApache License 2.0Apache-2.0

vssh

Author: Stéphane Martin

Contents

1   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)
    • 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.

2   install

Nothing special. Just copy the binary into your PATH.

3   compile

The dependencies are vondored using dep. You do not need it to compile vssh. Just clone in an appropriate directoty (GOROOT) and run make release.

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

4   develop

  • Clone the repository in an appropriate go directory.
  • Install dep and golangci-lint.
  • Compile with make debug and lint with make lint.

5   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.

5.1   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

5.2   interactive SSH session

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

5.3   remote command

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:

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

5.4   download

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

5.5   upload

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

5.6   as a library

TODO

6   examples

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

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

6.1   single sign on

Open a terminal, then authenticate yourself with Vault:

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:

vssh ssh me@myserver.example.org

6.2   execute a remote command

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

6.3   execute a remote command in a pseudo-terminal

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

6.4   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:

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:

env foo=bar ZOG=ZOG backupcommand

with the additional --upcase flag, it becomes:

env FOO=bar ZOG=ZOG backupcommand

or with the additional --prefix flag it becomes:

env secret_mysecret_foo=bar secret_mysecret_ZOG=ZOG backupcommand

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

7   questions

7.1   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)

7.2   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.