Vault Radar agent overview
The Vault Radar agent allows you to host Vault Radar scanning using your own deployment strategies. Configuration and management of the agent can be done through the HCP Vault Radar Portal, but all scanning will be performed by the agent. This can be useful if you are security conscious about where your content is being sent and scanned or if you have resources that are not publicly accessible by HCP.
Installation
The agent is part of the vault-radar
CLI. See here for instructions on downloading and installing the CLI.
For instructions on deploying the agent, see here.
Usage
In order to run the agent in an environment there are some required steps to complete in HCP and in the local environment you choose.
Create a service principal
Log into the HCP Portal to create your service principals. You can follow these instructions to create your Project service principals. You will need to create the service principals at the Admin level, more information about this level here. You will also need to generate a service principal key, and save the resulting Client Id and Client Secret.
Create an agent pool in the HCP Portal
An agent pool is a group of agents that share the same HCP_RADAR_AGENT_POOL_ID
, enabling higher throughput via horizontal scaling.
Navigate to the Vault Radar Portal and select Settings. Look for and select the Agent tab. If an agent pool already exists, you can select the Connect to Agent drop down, save the information, and move on to Settting up a data source.
If an agent pool does not exist, you will be prompted to create a new Agent Pool. Provide a name for your agent pool, used for display purposes. The next page provides instructions on how to download and install the latest version of the Vault Radar binary. Press the Next button to create the agent pool. You will be shown a page with the configuration information needed to configure an agent. Save this information now, but it can be retreived from the Agent tab on the Settings page. The information will have a placeholder values for the HCP_CLIENT_ID
and HCP_CLIENT_SECRET
due to their sensitive nature. You will need to provide to correct values from the service principal created for the agent when configuring your agent(s).
Connect a data source
A data source can be set up and managed from the Vault Radar module in the HCP Portal. Select Settings, then Data Sources, and then press the Add data source to begin.
Select agent scan.
Select the type of data source you'd like to setup and provide the information prompted by the data source's form.
Connect a Vault cluster
Policy
Vault Radar requires the following capabilities:
- Validate tokens (using self-lookup API)
- List and read all namespaces
- List all auth methods and mounts in each namespace
- List all secrets in a KV secrets engine mount
- Read all the versions of a secret in a KV secret engine mount
The following is a simple policy that grants Vault Radar broad access to your Vault Cluster.
The following is a policy granting just the required level of access but requires explicitly specifying the namespaces and KV mounts:
Agent configuration with Vault
A Vault cluster can be set up and managed from the Vault Radar module in the HCP Portal. Select Settings, then Index Sources, and then press the Add index source to begin.
- Select Vault and the Vault deployment type
- Provide you Vault cluster URL
- Select auth method and fill in details on the form, and select Next to validate the connection.
The Kubernetes authentication method enables Vault Radar to authenticate to Vault using Kubernetes service accounts. Use this method if you are running the Agent in a Kubernetes cluster.
- Follow the Vault Kubernetes authentication method documentation here.
- Replace
<your_cluster_host>
and<ca_cert>
with your cluster details. - Bind Kubernetes service accounts to Vault roles. Replace
<role_name>
,<service_account_name>
and<namespace>
with your setup details. - In the Vault Radar Agent configuration, set the Authentication Method to Kubernetes and provide the Authentication Path and Role Name where the Kubernetes role is configured.
Configure secret values
For most data sources the agent is going to need credentials to authenticate with the data source itself. When configuring your data source on HCP, you may be prompted to define a credential needed for the integration to work. Note: The agent is expecting a URI. Currently the only resource supported is an environment variable. An example of an environment variable URI is:
For example, if you are configuring a GitHub data source, you are going to need to generate a GitHub PAT for the Agent to use and save the value of that PAT local to the Agent as an environment variable. If you saved the environment variable as VAULT_RADAR_GIT_TOKEN
then the URI for that variable entered on HCP should be env://VAULT_RADAR_GIT_TOKEN
.
Additional configuration
The agent will respect configurations set by an .hashicorp/vault-radar/ignore.yaml
. See: