Privx-cmd
=========


# Overview

The privx-cmd tool routes OpenSSH connections through the PrivX SSH Bastion.

When used as the OpenSSH ProxyCommand, privx-cmd first launches a browser
for the user to log into PrivX, then sets up public-key authentication to PrivX
SSH Bastion, and finally starts relaying the connection between the SSH client
and PrivX SSH Bastion.


# Configuration And Usage

## Usage

Usage of privx-cmd:
  -browser string
        Command for launching browser
  -command string
        Command: connect, probe, logout (default "connect")
  -config string
        PrivX agent configuration file (default "~/.privx/agent.json")
  -d    Debug mode.
  -no-token
        Do not persist refresh token to file
  -privx string
        PrivX base URL
  -proxy-host string
        PrivX proxy hostname
  -proxy-port int
        PrivX proxy port (default 1080)
  -pub string
        SSH public key file (default "~/.ssh/id_privx.pub")
  -token string
        Token storage file (default "~/.privx/token.json")
  -v    Output version information and exit


## Establishing Trust With PrivX Server

The PrivX server must be trusted before privx-cmd can connect to it. This is
done by probing the PrivX server TLS certificate and persisting the server base
URL to disk:

   $ privx-cmd -command probe -privx https://example.privx.ssh.com
   PrivX server 'https://example.privx.ssh.com' certificate is untrusted
   Server TLS certificate:
     Issuer        OU=PrivX Web Server, CN=example.privx.ssh.com
     Subject       OU=PrivX Web Server, CN=example.privx.ssh.com
     Serial        2453081972165139088735051025889803929177292862
     Not Before    2020-10-27 12:56:06 +0000 UTC
     Not After     2022-10-27 13:06:06 +0000 UTC
     Fingerprints
       SHA1        BB 72 02 69 B7 4B 18 68 89 93 29 41 7F D8 65 94 4A 9F 10 D5
       SHA256      C7 B9 B9 D0 27 2E 5F A7 E6 0A 8D 0B 97 9D 7A 0C 3E CB 26 ...
   Would you like to add this server to trusted servers? Y/N: Y

After this, the server is stored to the PrivX Agent configuration file, by
default to ~/.privx/agent.json.


## Establishing Trust With PrivX SSH Bastion

We recommend adding the PrivX SSH-Bastion host key to SSH known_hosts file.

Fetch the host key by logging into PrivX and copying the SSH Bastion host key
from the Connections -> Native Clients page. For more information about adding
host keys to known_hosts, refer to your ssh client documentation.

Alternatively you can open a ssh connection to the PrivX SSH Bastion port 2222,
verify the displayed host key matches the fingerprint shown in the PrivX UI, and
accept the host key:
   $ ssh -p 2222 user@example.privx.ssh.com
   The authenticity of host '[example.privx.ssh.com]:2222 ([10.14.1.10]:2222)' \
   can't be established.
   ED25519 key fingerprint is SHA256:Cfdvb8QETyk0Vz9FhYd7UIH7RpvnREy2JWRXmvBh...
   Are you sure you want to continue connecting (yes/no/[fingerprint])?


## Generating an SSH Key Pair

We recommend generating a dedicated SSH key pair for use with privx-cmd.

By default privx-cmd reads the public key from ~/.ssh/id_privx.pub, but the file
location may be specified using the -pub command line option.

Note that the key pair must fullfil PrivX servers' constraints for public key
type and minimum size. Note also that PrivX server must be able to map a public
key to a PrivX user. Therefore the same public key cannot be used by multiple
PrivX users.


## Configuring OpenSSH ProxyCommand

Configure SSH client to use privx-cmd as the ProxyCommand when connecting to
target hosts. These configuration options can be specified in the client-user's
client configuration (typically at /etc/ssh/ssh_config​ or ​~/.ssh/config​​), for
example:

   Host *
       IdentityFile ~/.ssh/id_privx
       HostKeyAlias [example.privx.ssh.com]:2222
       ProxyCommand privx-cmd -privx https://example.privx.ssh.com %h %p

In this example the user's private and public key are stored in ~/.ssh/id_privx
and ~/.ssh/id_privx.pub respectively.


## Connecting To Targets

You can now connect to targets with the following command:

   $ ssh targetuser@target.example.com

This command performs the following:

1. If needed, privx-cmd launches a browser for the user to log into PrivX. Upon
   successful login privx-cmd gets an access token/refresh token. The refresh
   token is saved to ~/.privx/token.json for privx-cmd to reuse for later
   connections.

2. privx-cmd registers the user's public key as an authorized key to PrivX.

3. privx-cmd connects to SSH-Bastion's proxy port 1080, requests a connection to
   the target host, and starts relaying data between the SSH client and SSH
   Bastion.

Your connection to the final target is routed via PrivX SSH-Bastion. Connection
to PrivX SSH-Bastion is authenticated using public-key authentication.
On subsequent SSH connections privx-cmd attempts to use the saved refresh token
to fetch access tokens. If this succeeds the user is not required to re-login to
PrivX, so no browsers are launched.

Note that the following command removes any saved refresh tokens from the file
system, which forces the user to re-login on next SSH connection:

   $ privx-cmd -command logout


## Overriding Default Values With Command Line options

You can use privx-cmd command line options to override the default values.


### Using Non-Default Key Pair

To use SSH key pair stored to a non-default location, you can do the following:
* specify the public key file with the privx-cmd command line option -pub
* specify the corresponding private key file in the OpenSSH IdentityFile option


### Launching Non-Default Browser

Default command to launch the browser:
* linux: xdg-open {url}
* macOS: open {url}
* windows: cmd /c start {escaped url}

For example, to launch different browsers using the privx-cmd -browser option:
* linux: privx-cmd -browser /usr/bin/google-chrome
* macOS: privx-cmd -browser "open -a \"google chrome\""
* windows: privx-cmd.exe -browser "cmd /c start \"PrivX Login\" \"C:\Program Files\Google\Chrome\Application\chrome.exe\""

Privx-cmd appends the login URL to the command's argument list.

### Non-Default PrivX SSH Bastion Proxy Hostname Or Port

By default privx-cmd extracts the hostname from PrivX base URL and uses it as
the SSH Bastion proxy hostname. By default privx-cmd connects to SSH Bastion
proxy port 1080.

The SSH Bastion proxy hostname and port can be specified with the privx-cmd
options -proxy-host and -proxy-port.
