Install the DevOps Secrets Safe CLI

The DevOps Secrets Safe Command Line Interface (CLI), ssrun, is a Python package that wraps functionality exposed by the DevOps Secrets Safe API into a convenient client that is used to interact with the system.

Prerequisites

The DevOps Secrets Safe CLI is designed to run on any major platform supported by Python and that has Python 3.6 and pip3 or above available.

Install the Package with pip

The DevOps Secrets Safe CLI package, secretssafe, is installed and managed on a client machine by the Python package manager pip, through a WHL file supplied by BeyondTrust, and is located in the CommandLineInterface directory of the extracted archive.

Execute the following when running in a virtual environment:

pip install secretssafe-<version>-py3-none-any.whl

Conversely, execute the following when running outside a virtual environment:

pip3 install secretssafe-<version>-py3-none-any.whl

Execute the CLI

After a successful installation, the CLI can be run by executing the following from any location on the file system: ssrun

If the secretssafe package is installed inside a virtual environment, the environment must be first activated for ssrun to be on the path and thus executable.

Configure the Initial Context

Contexts allow for multiple DevOps Secrets Safe instances to be easily configured and accessed from a single client machine. On preliminary installation, execute the following to be prompted for details of the initial context:

ssrun context create

Follow the prompts to configure the DevOps Secrets Safe instance that the CLI initially interacts with. To view your configured clusters, execute the following:

ssrun context get
CURRENT    NAME       HOSTNAME/IP      PORT  API VERSION    SSL CA
*          localhost  localhost        8443  v1             false

The initial context is set to current (configuration to use during any other CLI action) on creation, and any subsequent contexts created can be configured as current with the following command:

ssrun context set-current -n <context_name>

In addition, specific environment variables can be used to override the current context:

export SECRETSSAFE_HOST=<IP address or hostname of Secrets Safe instance>
export SECRETSSAFE_PORT=<port of Secrets Safe instance>
The following variable is necessary if the certificate authority is not publicly trusted:
export SECRETSSAFE_VERIFY_CA=<path_to_ca_cert>

The DevOps Secrets Safe CLI verifies the SSL certificate presented by the DSS instance. The SECRETSSAFE_VERIFY_CA environment variable or SSL CA context attribute specifies the path to the CA certificate that the DSS certificate is checked against.

If no SECRETSSAFE_VERIFY_CA is specified, the default certificate bundles provided by the Python requests library are used.

Certificate verification can be disabled by setting SECRETSSAFE_VERIFY_CA=false. We strongly discouraged this practive for production environments.

To use these environment variables by default, rather than by manually managing contexts, you can make them persistent in the shell environment. They can be stored in a users ~/.bashrc file.

echo 'export SECRETSSAFE_HOST=1.1.1.1' >> ~/.bashrc 
echo 'export SECRETSSAFE_PORT=443' >> ~/.bashrc
echo 'export SECRETSSAFE_VERIFY_CA=false' >> ~/.bashrc
source ~/.bashrc	

In this example, certificate verification has been set to false. While this is convenient for testing, we do not recommend this for production environments.

Bash Autocompletion

The DevOps Secrets Safe CLI comes with the ability to configure bash autocompletion for ease of use and convenience. To install bash completion globally, execute the following:

ssrun completion bash > /etc/bash_completion.d/ssrun

This will allow any new bash instances to autocomplete the DevOps Secrets Safe CLI commands on demand. Sudo rights might be required to be able to write to /etc/bash_completion.d/.