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.

Nothing special. Just copy the binary into your PATH.

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

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

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.

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

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.

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:

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.

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.

TODO

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

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 [email protected]

vssh ssh [email protected] ls -al /

vssh ssh -t [email protected] zsh

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 [email protected] 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.

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)

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.