HashiCorp Cloud Platform
govern vault
Beta feature
This feature is currently available as beta. The beta functionality is stable but possibly incomplete and subject to change. We strongly discourage using beta features in production.
Note
You must have version 0.17.0 or higher of the Vault Radar CLI installed.
To check the current version of your CLI, use the version command.
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:
Mount | Resource | Method | Endpoint |
---|---|---|---|
System | List namespaces | LIST | sys/namespaces |
System | List auth methods | GET | sys/auth |
System | List secret mounts | GET | sys/mounts |
AppRole | List roles | LIST | auth/:mount-path/role |
AppRole | List secret ID accessors | LIST | auth/:mount-path/role/:role_name/secret-id |
AppRole | Lookup secret ID accessors | POST | auth/:mount-path/role/:role_name/secret-id-accessor/lookup |
KVv2 | Read KV engine config | GET | :mount-path/config |
Kvv2 | List secrets | LIST | :mount-path/metadata/:path |
KVv2 | Read secret metadata | GET | /:mount-path/metadata/:path |
KVv2 | Read secret version | GET | /:mount-path/data/:path?version=:version-number |
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.
Note
The VAULT_PARENT_NAMESPACE
will also work on Vault Enterprise but it is not
mandatory to set.