Your deployment key is a unique and secret identifier to your organization. You use it to enable the Threat Stack agent to properly connect it from your server to our backend. Most installs require you to define your deployment key when you push the agent to your host.
Store Your Deploy Key
Configuration Management Tools
If you use a configuration management tool, we recommend using their encryption system to manage your key (examples: Encrypted Hiera for Puppet, Vault for Ansible, Encrypted Data Bags for Chef, etc).
If you store your deployment key locally, encrypt the file and store it in an access-restricted directory.
Share your Deploy Key
If you share the key within your team, we recommend:
- Directing users to your Threat Stack organization to obtain the deploy key
If the user does not have direct access to your Threat Stack organization and they need the key:
- Use a password storage software (example: 1Password or LastPass)
- Threat Stack will never ask for your deploy key by email - do not email your deploy key
- Obscure the deployment key when screen sharing and in screenshots
- In the case of cloud-init, be sure you’re using a trusted Cloud Provider
Risks of a Deploy Key
The main risk associated with a deploy key is that key could be leaked and used maliciously.
If your deployment key is leaked, malicious users can deploy agents on their own systems and flood your Threat Stack organization with events and alerts from outside systems. This will make proper monitoring of your infrastructure’s hosts much more difficult and hinder your ability to quickly respond to real threats.
You can reduce a risk of a leak by:
Obscuring deploy key information on screenshots, including:
- Diagnostic images
- Agent deployment images
Limiting screen sharing of agent deployments to only trusted users.
Threat Stack will never ask for your deploy key by email - do not email your deploy key
Rotate a Deploy Key
Rotation of a deploy key is typically recommended only in the event you believe your previous deployment key was compromised.
Examples of deployment key compromise:
- The deployment key was unintentionally shared by a screenshot of agent deployment command line or other image
- An unauthorised user accessed your organisation
If you rotate your deployment key, future deployments of the agent must use the new key to register to the platform. Agents cannot connect and send data without first registering with your organization’s deploy key.
Threat Stack continues to monitor all active, previously deployed hosts as they no longer need the deploy key after registration. However, your previous key will no longer work for deploying agents on new hosts.
Additionally, you will need to update your automation tools and key managers such as Chef, Ansible, Puppet, and 1Password with the new deployment key.
If you do not update these automation tools and key managers, any new hosts that you create will not be populated and monitored in Threat Stack. Depending on how you configured your automation tools, this may lead to failed runs or bootstrapping of servers into your environment.
How to Rotate a Deploy Key
If you believe your deployment key has been compromised, navigate to your Threat Stack organization:
- Go to the Settings page and access the Application Keys tab
- Click the Reset Deployment Key button, a new deploy key will display
Now that you have rotated your deploy key, you will need to update any automation tools and key managers that you use. If you do not update these automation tools and key managers, any new hosts that you create will not be populated and monitored in Threat Stack.