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 Next-Gen WAF agent.
• Vault to rotate or replace site keys. When Vault replaces keys, the Vault agent updates the configuration file for the relevant Next-Gen WAF agent and restarts the Next-Gen WAF agent.
• authenticated applications, services, and machines to read site keys that are stored in Vault.

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 key rotation process automatically restarts the Next-Gen WAF agent. Due to the agent's brief downtime during key rotation, we recommend rotating the keys during a maintenance window.
• The Signal Sciences plugin for HashiCorp Vault is only supported on Linux on x86 CPU architectures.

Set up plugin

To set up the plugin for the first time on systems that use systemd, 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:

    1template {
    2  source = "/etc/signalsciences/agent.ctmpl"
    3  destination = "/etc/signalsciences/agent.conf"
    4}

    The Vault agent automates the rendering of the Next-Gen WAF agent configuration template when the site keys are rotated.

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

    1{{ with secret "sigsci/creds/vault-user/sites/<site-name>" }}
    2accesskeyid={{ .Data.accessKey }}
    3secretkey={{ .Data.secretKey }}
    4{{ 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/signalsciences/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 Next-Gen WAF 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: