Secrets Vault

CoyoteDX contains an internal secrets vault to store user names, passwords, URLs and free-form notes in an encrypted file protected by one master password. This allows your data transfer jobs to reference secrets in the vault by their identifiers and not expose passwords and other confidential data in your jobs configuration files.

The vault is an AES-256 encrypted file which contains as many entries as you need. Each entry contains several fields, holding more than just a password. It is a relatively compact file and should be safe to check into your source code management system (although it is a binary file).

Vault Management

The vaults can be created and managed using the Coyote Vault application contained within Coyote DX. It can be called by typing csv at the command line and a GUI will load which allows you to manage entries and vault files. Some teams have used Coyote Vault to manage secrets for their regular day-to-day activities; not just for data transfer jobs.

Specifying the Vault

Using the secrets vault is a simple matter of adding a line to your data transfer job:

"Vault": { "source": "devops.vault" },

This loads the devops.vault file and places it in the Template facility under the name of Vault.

Accessing Secrets

Secrets stored in the vault are accessed through templates; nearly every configuration option is passed through the templating facility which allows you to insert vault entries into those configuration strings:

"password": "[#Vault.get(Bob,password)#]"

The above gets the password for the "Bob" entry. Note there is no $ after the opening delimiter. This is because the secret is not in the symbol table, it is accessed through the Vault object which wraps the vault. [#$Vault#] references the Vault symbol (i.e. variable) and [#Vault#] references the Vault object in the template cache. Object references allow the template facility to perform more complex processing to return values than a simple table lookup of scalar values.

The Vault object contains two methods, get(String) and get(String, String). The first returns the default secret for identified vault entry. This is normally the password, but it depends on the underlying secrets provider (multiple vault implementations are possible). The second method signature returns the named attribute of the identified vault entry. The following two lines are equivalent:

"password": "[#Vault.get(Bob)#]"
"password": "[#Vault.get(Bob,password)#]"

It is possible to get the username for Bob thusly:

"password": "[#Vault.get(Bob,username)#]"

The fields in the default vault implementation are described below:

• name - the name of the entry, how it is accessed.
• url - a general-purpose URL
• username - user name
• password - credential
• notes - freeform notes for the entry

Specifying the Master Password

The vault looks for the master password to decrypt the vault in a system property named vault.secret which must be specified at the time the job is run. This can be done on the command line: -Dvault.secret=MySecretPassword but many teams will create an entry in the cxd_pre.bat or cdx_pre.sh and set the property before each Coyote DX job is run. For example:

@if "%DEBUG%" == "" @echo off
set CDX_OPTS= -Dvault.secret=MySecretPassword

The cdx_pre scripts are located in the home directory of the user running Coyote DX. NOTE: the cdx_pre scripts should be protected from being read by any other user. Making this file readable by only the owner helps prevent anyone else from accessing the master password. Your secrets are only as secure as your master password.

Additionally, it is a good idea to create a compensating entry in the cdx_post scripts to remove the password from your environment variables once the job completes:

@if "%DEBUG%" == "" @echo off
@rem this clear the secret key so other processes can't see it later
set CDX_OPTS= -Dvault.secret=

Additional Providers

The secrets vault facility is modular and designed to support multiple secrets providers. Work is underway to support CyberArk and a few others. These will be provided as additional modules in the future.

Configuring providers look like the following:

"Vault": {
    "provider": "CyberArk",
    "method": "agent"
},