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 agent scan

Select the type of data source you'd like to setup and provide the information prompted by the data source's form.

Select a data source to scan

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.


path "*" {
    capabilities = ["read", "list"]
}

The following is a policy granting just the required level of access but requires explicitly specifying the namespaces and KV mounts:


path "auth/token/lookup-self" {
    capabilities = ["read"]
}

# Assumption: Namespaces are atmost 2 levels deep
path "sys/namespaces/*" {
    capabilities = ["read", "list"]
}

path "+/sys/namespaces/*" {
    capabilities = ["read", "list"]
}

path "+/+/sys/namespaces/*" {
    capabilities = ["read", "list"]
}

path "sys/auth" {
    capabilities = ["read"]
}

path "+/sys/auth" {
    capabilities = ["read"]
}

path "+/+/sys/auth" {
    capabilities = ["read"]
}

path "sys/mounts" {
    capabilities = ["read"]
}

path "+/sys/mounts" {
    capabilities = ["read"]
}

path "+/+/sys/mounts" {
    capabilities = ["read"]
}

# Assumption: KV secret engine mounts are atmost 2 levels deep
path "+/metadata/*" {
    capabilities = ["read", "list"]
}

path "+/+/metadata/*" {
    capabilities = ["read", "list"]
}

path "+/+/+/metadata/*" {
    capabilities = ["read", "list"]
}

path "+/+/+/+/metadata/*" {
    capabilities = ["read", "list"]
}

path "+/data/*" {
    capabilities = ["read"]
}

path "+/+/data/*" {
    capabilities = ["read"]
}

path "+/+/+/data/*" {
    capabilities = ["read"]
}

path "+/+/+/+/data/*" {
    capabilities = ["read"]
}

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 a index source to scan

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.

vault write auth/kubernetes/config \
 kubernetes_host=https://<your_cluster_host> \
 kubernetes_ca_cert=@<ca_cert> \
 disable_local_ca_jwt=true

Bind Kubernetes service accounts to Vault roles. Replace <role_name>, <service_account_name> and <namespace> with your setup details.

vault write auth/kubernetes/role/<role_name> \
  bound_service_account_names=<service_account_name> \
  bound_service_account_namespaces=<namespace> \
  policies=<vault_policy>

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.

Kubernetes authentication configuration

The AppRole authentication method is ideal for systems that don't run in Kubernetes, allowing flexible programmatic access.

Follow the AppRole Auth Method process for a Vault cluster here. After setup, you will have an AppRole role ID and secret ID created in Vault.

Create an AppRole, replace <role_name> with your setup details.

vault write auth/approle/role/<role_name> policies=<vault_policy>

Retrieve the role ID and secret ID.

vault read auth/approle/role/<role_name>/role-id
vault write -f auth/approle/role/<role_name>/secret-id

Save the role ID and secret ID as environment variables for the Agent.
```
export VAULT_ROLE_ID=<role_id>
export VAULT_SECRET_ID=<secret_id>
```
From the UI, select the App Role authentication method and provide the Authentication Path and the role ID and secret ID environment variables.

The token-based method uses Vault's generated tokens for authentication. This method is more straightforward and easy to use.

Generate a valid Vault token by following the steps here.
Set the token as an environment variable for the Agent.
```
export VAULT_TOKEN=<vault_token>
```
From the UI select Token for the Authentication method and then provide the environment variable just configured. (ex. env://VAULT_TOKEN)

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:

$ env://ENV_VARIABLE_NAME

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:

Custom ignore rules