Acquisition complete HashiCorp officially joins the IBM family. Learn more
HashiCorp Cloud Platform
HCP Vault Radar operations

Install HCP Vault Radar agent

  • 9min
  • |
  • HCP
  • Vault

HCP Vault Radar automates the detection and identification of unmanaged secrets in your code so that teams can take appropriate actions to remediate issues.

In the quickstart series of tutorials, you followed HashiCups (a fictitious company) as they set up a proof-of-concept (POC) to use HCP Vault Radar. You set up Vault Radar to scan GitHub repositories for secrets, set up alerts, and automate the creation of support tickets. In this tutorial, you will install the HCP Vault Radar agent in your Kubernetes environment to enable on-premises secret scanning and correlate findings with Vault.

Scenario

HashiCups completed their POC and wants to integrate additional on-premises data sources with Vault Radar. They would also like to determine if HashiCorp Vault stores any secrets that match the findings from the Vault Radar scans.

Alice from the architect team designed the implementation of the Vault Radar agent to their Kubernetes cluster with a dedicated Kubernetes service account. Oliver from the operations team, is going to deploy the Vault Radar agent in their Kubernetes environment. The Vault Radar agent enables you to scan on-premises data sources and correlate findings with HashiCorp Vault.

You will take on the role of Oliver to complete the installation of the Vault Radar agent and scan a Git repository.

Prerequisites

Set up the lab

In this tutorial, you will use a public GitHub repository. You can scan both public data sources and on-premises data sources with the Vault Radar agent.

Configure GitHub

  1. Log in to your GitHub account and access the hcp-vault-radar-foundations repository.

  2. Create a fork of the repository and select the desired organization.

  3. Review the main.go file. Lines 11 and 12 include a username and password. This username and password represent secrets that HashiCups does not want included in their source code.

  4. Copy and paste the following URL into your browser. This URL pre-fills the personal access token form with the permissions needed by the Vault Radar agent.

    https://github.com/settings/tokens/new?scopes=repo,read:org,admin:repo_hook,admin:org_hook,read:user

    Note

    Set a personal access token TTL according to your organization's current best operational practices. Refer to the GitHub documentation for more information on personal access token.

  5. Enter vault-radar-agent in the Note field.

  6. Click Generate token.

  7. Copy the token and open a new terminal.

  8. Export an environment variable for the token.

    $ export VAULT_RADAR_GIT_TOKEN=ghp...snip...Xoq

    You will use this token to authenticate the Vault Radar agent with your GitHub account.

Start minikube

  1. From the terminal where you exported the GitHub personal access token, create a minikube cluster.

    $ minikube start
😄  minikube v1.30.1 on Darwin 13.4 (arm64)
✨  Automatically selected the docker driver
📌  Using Docker Desktop driver with root privileges
👍  Starting control plane node minikube in cluster minikube
🚜  Pulling base image ...
🔥  Creating docker container (CPUs=2, Memory=4000MB) ...
🐳  Preparing Kubernetes v1.26.3 on Docker 23.0.2 ...
   ▪ Generating certificates and keys ...
   ▪ Booting up control plane ...
   ▪ Configuring RBAC rules ...
🔗  Configuring bridge CNI (Container Networking Interface) ...
   ▪ Using image gcr.io/k8s-minikube/storage-provisioner:v5
🔎  Verifying Kubernetes components...
🌟  Enabled addons: storage-provisioner, default-storageclass
🏄  Done! kubectl is now configured to use "minikube" cluster and "default" namespace by default

    The minikube CLI starts a single-node cluster and configures kubectl for the cluster.

  2. Verify the cluster is running.

    $ minikube status
minikube
type: Control Plane
host: Running
kubelet: Running
apiserver: Running
kubeconfig: Configured

    minikube is running and ready to use.

Prepare HCP Vault Radar

You need to create a service principal in HCP to authenticate the Vault Radar agent and a client pool for the agent.

Create a service principal

The Vault Radar agent uses a HCP service principal to authenticate with HCP.

  1. Log in to the HCP Portal, select your organization and the project you want to configure Vault Radar for.

  2. Click Access control (IAM).

  3. Click Service principals.

  4. Click Create service principal.

  5. Enter vault-radar-agent in the Service principal name text box.

  6. Click the Select service pull-down menu and select Vault Radar.

  7. Click the Select role(s) pull-down menu and select Vault Radar Agent.

  8. Click Create service principal.

  9. On the vault-radar-agent screen, click Keys.

  10. Click Generate key.

  11. Copy the Client ID and return to the terminal where you started minikube.

  12. Export an environment variable for the client ID.

    $ export HCP_CLIENT_ID="your-client-id"

  13. Return to the HCP Portal and copy the Client secret.

  14. Return to the terminal where you exported the HCP_CLIENT_ID environment variable and export the HCP_CLIENT_SECRET environment variable.

    $ export HCP_CLIENT_SECRET="your-client-secret"

  15. Return to the HCP Portal and close the Save your key dialog box. You will not be able to retrieve the client secret again once you close the dialog box.

Create a client pool

  1. From the Keys page click Back to service principals, and then click Back to Dashboard.

  2. Click Vault Radar.

    Note

    If you have not used Vault Radar before, click View Vault Radar.

  3. Click Settings.

  4. Click Agent.

  5. Click Add an agent pool.

  6. In the Agent pool name text box, enter vault-radar-agent-pool.

  7. Click Save and continue.

    The Install the agent tab displays the steps to run the agent interactively using the Vault Radar CLI. This tutorial focuses on the preferred method of running the agent in production, which is to deploy the agent in a Kubernetes cluster.

  8. Click Install agent.

  9. Copy the export HCP_PROJECT_ID=... and export HCP_RADAR_AGENT_POOL_ID=... commands.

  10. Return to the terminal where you exported the HCP_CLIENT_ID environment variable and paste the commands to export the project ID and pool ID.

    $ export HCP_PROJECT_ID=abc...snip...123 
export HCP_RADAR_AGENT_POOL_ID=def...snip...456

  11. Verify you have the required environment variables set.

    $ printenv | grep -e HCP_ -e VAULT_
HCP_CLIENT_ID=RQO...snip...omK
HCP_CLIENT_SECRET=f3r...snip...Ldp
HCP_PROJECT_ID=abc...snip...123 
HCP_RADAR_AGENT_POOL_ID=def...snip...456
VAULT_RADAR_GIT_TOKEN=ghp...snip...42

    The vault-radar-agent-pool dialog will remain in the Awaiting connection state until you complete the next section.

Deploy HCP Vault Radar agent

You have set up and collected the information necessary to deploy the Vault Radar agent.

The Vault Radar agent can run interactively using the Vault Radar CLI, or the preferred method of deploying the agent in a Kubernetes cluster. In this section, you will deploy the agent in your minikube cluster.

  1. Create a Kubernetes namespace for the Vault Radar agent.

    $ kubectl create -f - <<EOF
apiVersion: v1
kind: Namespace
metadata:
  name: vault-radar
  labels:
    app: vault-radar-agent
EOF

    Example output:

    namespace/vault-radar created

    A good practice is to separate workloads into dedicated namespaces.

  2. Create a service account for the Vault Radar agent in the vault-radar Kubernetes namespace.

    $ kubectl create -f - <<EOF
apiVersion: v1
kind: ServiceAccount
metadata:
  name: vault-radar-agent
  namespace: vault-radar
  labels:
    app: vault-radar-agent
EOF

    Example output:

    serviceaccount/vault-radar-agent created

  3. Deploy the Vault Radar agent.

    $ kubectl create -f - <<EOF
apiVersion: apps/v1
kind: Deployment
metadata:
  name: vault-radar-agent
  namespace: vault-radar
  labels:
    app: vault-radar-agent
spec:
  replicas: 2
  selector:
    matchLabels:
      app: vault-radar-agent
  template:
    metadata:
      labels:
        app: vault-radar-agent
    spec:
      serviceAccountName: vault-radar-agent
      automountServiceAccountToken: true
      containers:
        - name: vault-radar-agent
          image: docker.io/hashicorp/vault-radar:latest
          command: ["vault-radar"]
          args: ["agent", "exec"]
          imagePullPolicy: Always
          tty: true
          resources:
            limits:
              cpu: 1000m
              memory: 1024Mi
            requests:
              cpu: 100m
              memory: 512Mi
          env:
            - name: HCP_PROJECT_ID
              value: "$HCP_PROJECT_ID"
            - name: HCP_RADAR_AGENT_POOL_ID
              value: "$HCP_RADAR_AGENT_POOL_ID"
            - name: HCP_CLIENT_ID
              value: "$HCP_CLIENT_ID"
            - name: HCP_CLIENT_SECRET
              value: "$HCP_CLIENT_SECRET"
            - name: VAULT_RADAR_GIT_TOKEN
              value: "$VAULT_RADAR_GIT_TOKEN"
EOF

    Example output:

    deployment.apps/vault-radar-agent created

  4. Check the status of the deployment.

    $ kubectl get pods --namespace vault-radar
NAME                                 READY   STATUS    RESTARTS   AGE
vault-radar-agent-7cc47fb9d6-n24rb   1/1     Running   0          10s
vault-radar-agent-7cc47fb9d6-v6nbw   1/1     Running   0          10s

    Note

    If the pod status is CrashLoopBackOff, check the environment variable values.

    The Vault Radar agent is running in your Kubernetes cluster.

Scan a data source

With the Vault Radar agent deployed, you can now scan a data source. The agent can scan on-premises data sources such as a self-hosted Git environment, or public data sources such as GitHub.

  1. Return to the HCP Portal.

  2. The vault-radar-agent-pool Status should now display Connected.

  3. Click Finish.

  4. Click Add data sources to agent pool.

  5. Select GitHub Cloud.

  6. Enter the name for the GitHub organization you forked the hcp-vault-radar-foundations repository to.

  7. Enter the URI for the GitHub personal access token environment variable.

    env://VAULT_RADAR_GIT_TOKEN

  8. Click Next.

  9. On the Select repositories to monitor page, select the Select repositories to monitor radio button.

  10. Click the checkbox for the hcp-vault-radar-foundations repository, and click Finish (1 selected).

    Vault Radar starts scanning the repository for secrets. Once complete, the Top 10 resource risks dashboard displays the findings.

    Example dashboard: HCP Vault Radar portal displaying the top 10 resource risks dashboard based on Vault Radar scanning a repository for secrets

Clean up

In the next tutorial, you will update the Vault Radar agent to correlate its findings with secrets stored in HashiCorp Vault. If you plan to continue with the next tutorial, do not perform these clean up steps.

  1. Delete the minikube cluster.

    $ minikube delete

  2. Delete the forked GitHub repository from your GitHub organization.

  3. Delete the GitHub personal access token created in this tutorial.

Summary

In this tutorial, you installed the HCP Vault Radar agent in your Kubernetes environment. You then added a data source to the agent pool and scanned a GitHub repository for secrets. All scanning takes place on the agent in your Kubernetes cluster. The agent sends only the hashed findings to the HCP Vault Radar portal.

Additional resources

Collection Overview

HCP Vault Radar operations

 Next

Correlate findings with Vault