govern vault

The govern vault command is used for scanning a HashiCorp Vault Community Edition or Enterprise cluster. Scanning Vault using govern vault provides compliance reporting and secrets indexing capabilities.

Authentication and authorization

vault-radar requires the VAULT_ADDR and VAULT_TOKEN environment variables in order to connect to your Vault cluster. The govern vault command will traverse the full namespace hierarchy. Within each namespace, an attempt to scan every AppRole and KVv2 mount will be made. Access can be limited via the policies attached to the token provided. vault-radar will attempt to use the following endpoints:

Compliance reporting

The govern vault command can be used to detect secrets that need to be rotated to meet organization compliance requirements. The output will contain entries for AppRole and KVv2 secrets. AppRole secrets will have an entry per secret ID accessor. KVv2 secrets will have an entry per secret sub-key, per version, per KVv2 secret. For example, there will be 6 entries for a secret with 3 versions that contains an AWS access key ID and secret key. KVv2 secret entries will include a hashed version of the secret value. We will not have access to AppRole secret ID values as those are only provided upon creation. Secret hashes can be used as a mechanism to detect that a secret has been sprawled within Vault across multiple entries, mounts, or namespaces.

The following command will scan Vault providing CSV output with a rotation period of 90 days:

$ vault-radar govern vault --outfile vault-scan.csv --rotation-period=90

Secrets with an age greater than 90 days will have medium severity and provide a warning of Secret rotation period has been exceeded. Warnings will also be provided if a secret is close to exceeding its expiry period (provided by -expiry-period) or if its number of uses (currently specific to AppRole) is close to 0. Entries with multiple warnings will have a severity of high.

The breadth of a scan can be limited and filtered in multiple ways. Most simply, the -limit flag can be used to specify a maximum number of secrets to scan. There are no ordering guarantees with this flag, however, so it is mostly useful to capture a quick subset of data as a means to fully understand the output's structure. The output can also be filtered more directly using one or more of the following flags:

• -namespace: Only secrets within this namespace will be present in this namespace. Example: vault-radar govern vault -namespace=ns1 ...
• -mount-type: Only secrets within mounts of this type will be present in the output. This flag is namespace and path agnostic. Example: vault-radar govern vault -mount-type=approle ...
• -mount-path: Only secrets within mounts of this relative path will be present in the output. This flag is namespace and mount-type agnostic. Example: vault-radar govern vault -mount-path=app1 ...

HCP connection scanning behavior

The default behavior of govern commands is to require an HCP cloud connection. This is to ensure that hashes are generated using a shared salt from the cloud keeping consistency across scans. In order to populate the HCP connection information needed, refer to the HCP upload page.

To allow for govern commands to continue working without the need for HCP cloud connection you can use the new --offline flag as such.

$ vault-radar govern vault --offline -o <PATH TO OUTPUT>.csv

HCP Vault Dedicated considerations

In a HCP Vault Dedicated cluster, the root namespace is restricted and the users will only have access to admin namespace and all the child namespaces within it. For vault-radar govern vault to work against a HCP Vault Dedicated cluster, it is mandatory to set VAULT_PARENT_NAMESPACE environment variable to the namespace that needs to be scanned.

$ export VAULT_PARENT_NAMESPACE=admin
$ vault-radar govern vault --outfile govern-results.csv --rotation-period=90

The above command will scan all the namespaces within the admin, including the admin namespace.