HashiCorp Vault

With the Signal Sciences plugin for HashiCorp Vault, you can use Vault to manage the keys for your agents. Vault is an identity-based secrets and encryption management system.

Specifically, the plugin allows:

• Vault to store the Agent Access Keys and Agent Secret Keys for your sites.
• the Vault agent to pull the keys from Vault when needed and give the keys to the deployed Signal Sciences agent.
• Vault to rotate or replace site keys. When Vault replaces keys, the Vault agent updates the configuration file for the relevant Signal Sciences agent and restarts the Signal Sciences agent.
• authenticated applications, services, and machines to read site keys that are stored in Vault.

Important: This information is part of a beta release. For additional details, read our product and feature lifecycle descriptions.

Limitations and considerations

Before setting up the plugin and managing site keys in Vault, keep the following in mind:

• To use the Signal Sciences plugin for HashiCorp Vault, Vault must already be installed and configured to load external plugins.
• The Signal Sciences agent is restarted as part of the key rotation process. Due to the agent’s brief downtime during key rotation, we recommend rotating the keys during a maintenance window.

Set up plugin

To set up the plugin for the first time, follow these steps:

1. Using the curl command line tool, copy the plugin binary to the external plugins directory:

    curl -O https://dl.signalsciences.net/vault-plugin-sigsci/latest/vault-plugin-sigsci.tar.gz
    tar xzvf vault-plugin-sigsci.tar.gz
    vault plugin register -sha256=$(sha256sum vault-plugin-sigsci|cut -c-64) secret vault-plugin-sigsci
   

2. Using the command line, enable the plugin:

    vault secrets enable -path=sigsci vault-plugin-sigsci
   

   Vault mounts the plugin at path /sigsci.

3. Create a user for the plugin. Assign the user the User role. An invitation email is sent to the email address you supplied for the plugin user.

4. From the plugin user’s email account, open the invitation email and click Accept invite. The account creation form appears.

5. Fill out the account creation form:

   • Leave the Email address field as is.
   • In the Name field, enter vault-user.
   • In the Password field, enter a password for the account.
   • In the Confirm password field, enter the password again.

6. Click Create account.

7. Create an API access token for the plugin user. Signal Sciences cloud API credentials are required for reading and managing agent site keys.

8. Using the command line, copy the API access token to token.txt file:

   vault write -f /sigsci/role/vault-user corp=<corp-id> email=<email-id> token=@token.txt
   

   Replace <corp-id> with the ID of your corp and <email-id> with the plugin user’s email address.

9. Using the command line, copy site keys for a single site or all sites to vault:

   vault write -f /sigsci/creds/vault-user/sites/<site-name>
   

   Replace <site-name> with the name of the site.

   or

    vault write -f /sigsci/creds/vault-user/sites/
   

10. Install and configure the Vault agent using the following template:

     template {
       source = "/etc/signalsciens/agent.ctmpl"
       destination = "/etc/signalsciens/agent.conf"
     }
    

    The Vault agent automates the rendering of the Signal Sciences agent configuration template when the site keys are rotated.

    Example content of the configuration template /etc/signalsciens/agent.ctmpl:

    {{ with secret "sigsci/creds/vault-user/sites/<site-name>" }}
    accesskeyid={{ .Data.accessKey }}
    secretkey={{ .Data.secretKey }}
    {{ end }}
    

11. Using the command line, create a systemd service to restart the agent:

     sudo tee -a /etc/systemd/system/sigsci-agent-restart.service <<END
    [Unit]
    Description="signalsciences agent restarter"
    
    [Service]
    Type=OneShot
    ExecStart=/usr/bin/systemctl restart sigsci-agent.service
    
    [Install]
    WantedBy=multi-user.target
    END
    

12. Using the command line, create a configuration file watcher:

     sudo tee -a /etc/systemd/system/sigsci-agent-restart.path <<END
    [Path]
    PathChanged=/etc/signalsciens/agent.conf
    
    [Install]
    WantedBy=multi-user.target
    END
    

13. Using the command line, start and enable the configuration file watcher:

     systemctl enable --now sigsci-agent-restart.service
    

Rotate site keys

To rotate the keys for a site, replace the keys in Vault, restart the Signal Sciences agent, and then delete the non-primary keys in Vault:

1. Using the command line, rotate a site key in Vault:

    vault write -f /sigsci/rotate/sites/<site-name>
   

   Replace <site-name> with the name of the relevant site.

2. Using the command line, delete the non-primary keys in Vault:

   vault delete /sigsci/rotate/sites/<site-name>
   

   Replace <site-name> with the name of the relevant site.

Manage plugin roles and keys

Once the plugin is set up, you can use the command line to perform these actions: