vault-ssh-plus

README

vault-ssh-plus (vssh)

An enhanced implementation of vault ssh, wrapping the OpenSSH ssh client to eliminate the management overhead of using of short-lived SSH client keys CA-signed by @hashicorp Vault.

Features

• Support for all ssh(1) capabilities, including:
  • non-filesystem private keys (e.g. gpg-agent, PKCS#11, etc.);
  • arbitrary ssh_config(5) configuration (e.g. Host aliases and Match clauses);
  • ControlMaster connection sharing.
• Automatic and transparent just-in-time delivery of short-lived, CA-signed, single-use ssh client keys.
• Adherence to the Principal of Least Privilege: by default, signed keys only permit the specific extensions required for the ssh options given.
• Automatic username mapping for Vault roles with a single, fixed entry in allowed_users (e.g. root, jenkins, ansible).
• Significantly lower memory overhead than vault ssh.

Requirements

• A HashiCorp Vault instance configured for SSH Client Key Signing, access to an appropriate role, and an SSH server configured to trust the Vault CA.
• An active Vault token (either in the VAULT_TOKEN environment variable, or – if the standard vault binary is available within $PATH – available from a Vault Token Helper). The VAULT_ADDR environment variable must also be set.
• OpenSSH 7.2 or newer ssh client binary.
• A standard SSH private key (stored anywhere supported by ssh), and the associated unsigned public key (default: ~/.ssh/id_rsa.pub). vssh does not require access to the private key.

Usage

In addition to all the options accepted by ssh(1), vssh accepts the following options:

$ vssh --help
Usage:
  vssh [options] destination [command]

Application Options:
      --version                           Show version

Vault SSH key signing Options:
      --path=                             Vault SSH Path (default: ssh) [$VAULT_SSH_PATH]
      --role=                             Vault SSH Role (default: default) [$VAULT_SSH_ROLE]
      --ttl=                              Vault SSH Certificate TTL (default: 300) [$VAULT_SSH_TTL]
  -P, --public-key=                       OpenSSH Public RSA Key to sign (default: ~/.ssh/id_rsa.pub) [$VAULT_SSH_PUBLIC_KEY]

Certificate Extensions:
      --default-extensions                Disable automatic extension calculation and request signer-default extensions [$VAULT_SSH_DEFAULT_EXTENSIONS]
      --agent-forwarding                  Force permit-agent-forwarding extension [$VAULT_SSH_AGENT_FORWARDING]
      --port-forwarding                   Force permit-port-forwarding extension [$VAULT_SSH_PORT_FORWARDING]
      --no-pty                            Force disable permit-pty extension [$VAULT_SSH_NO_PTY]
      --user-rc                           Enable permit-user-rc extension [$VAULT_SSH_USER_RC]
      --x11-forwarding                    Force permit-X11-forwarding extension [$VAULT_SSH_X11_FORWARDING]

Help Options:
  -h, --help                              Show this help message

If you need to override the SSH Client Key Signing mountpoint or role, this is most easily achieved by setting the VAULT_SSH_PATH and VAULT_SSH_ROLE environment variables in your shell rc.

Similarly, if you prefer an ed25519 or ecdsa key, override with VAULT_SSH_PUBLIC_KEY.

By default, the certificate will be requested with only those extensions required for the current command (default permit-pty unless -N is specified). Additional extensions may be requested (e.g. to support expected future multiplexed connections) with the "Certificate Extensions" arguments, or the Vault role default extensions may be forced with --default-extensions.

Example

The following will request that the ed25519 public key be signed by the Vault signed at https://vault.example.com:8200/v1/ssh/sign/ssh-client-signer, with permit-pty and permit-port-forwarding extensions to support the connection to host.example.com

$ export VAULT_ADDR=https://vault.example.com:8200 VAULT_SSH_PATH=ssh-client-signer VAULT_SSH_PUBLIC_KEY=~/.ssh/id_ed25519.pub
$ vault login -method=oidc
...
$ vssh -L8080:localhost:80 host.example.com
...

Installation

Manual

Download and extract the latest release.

macOS

brew install isometry/tap/vault-ssh-plus

Ansible

If you've already installed my release-from-github role:

ansible -m import_role -a name=release-from-github -e release_repo=isometry/vault-ssh-plus -e release_hashicorp_style=yes localhost

Troubleshooting

Refer to the Vault Documentation