HashiCorp Vault Integration Guide

Overview

This guide outlines how to install and prepare HashiCorp Vault so the discovery extension can enumerate certificates and keys, how to generate the read-only credentials it needs, and how to enter those credentials into the discovery configuration. Steps are given for both the Vault Web UI and the Vault CLI.

The discovery reads material from three Vault secrets engines:

  • PKI: issued certificates and CA certificates
  • Transit: encryption key details such as type, size, and version
  • KV: certificates and keys stored inside key-value secrets

Discovery is read-only. It never creates, changes, exports, or deletes anything in Vault.

Two ways to work. Everything below can be done two ways. Pick whichever you prefer for each step:

Mode How you access it Best for
Web UI A browser pointed at https://<vault_host>:8200/ui Point and click setup, one off changes
CLI The vault command line tool on your computer Scripting, copy and paste setup, generating
credentials

The address 8200 is the Vault default port. Replace with your server hostname or IP. Use http:// only for local testing. Use https:// for anything real.

Prerequisites

Before beginning, confirm the following:

  1. A machine (Linux, macOS, or Windows) to run the Vault server, reachable on the network from wherever discovery runs.
  2. Administrative access to Vault (a root token, or an admin account), needed to create policies and authentication credentials.
  3. Optional: the vault CLI installed on your own computer if you want to use the command line. Download it from https://developer.hashicorp.com/vault/install.

Step-by-Step Guide

Step 1: Install and Start Vault

If you already have a running Vault with certificates and keys in it, skip to Step 3.

Option A: Quick start for evaluation (dev mode)

Dev mode runs a ready-to-use Vault in memory with the UI enabled. It is for testing only. Data is lost on restart.

CLI 
vault server -dev

On startup Vault prints two things you must copy:

  • Api Address, for example http://127.0.0.1:8200. This becomes your Vault URL.
  • Root Token, for example hvs.XXXXXXXXXXXXXXXX. This is your initial admin login.

If discovery runs on a different machine than Vault, replace 127.0.0.1 with the real hostname or IP of the server so it is reachable.

Web UI

Open http://127.0.0.1:8200/ui in a browser, choose Token as the method, and paste the Root Token.

Option B: Persistent install (for real use)

  1. Download and install the Vault binary from https://developer.hashicorp.com/vault/install.
  2. Create a configuration file (storage plus listener) per the HashiCorp documentation, then start the server:
    3. bash vault server -config=vault-config.hcl
  3. Initialize Vault once to get your unseal keys and the first root token:
    4. bash vault operator init

    Save the Unseal Keys and Initial Root Token somewhere safe.

  4. Unseal Vault (repeat with different keys until it reports unsealed):
    5. bash vault operator unseal
  5. You can now open the Web UI at https://<vault_host>:8200/ui and log in with the root token.

    6. Step 2: Point Your Tools at Vault

    Web UI

    Browse to https://:8200/ui and sign in with your token (or admin account).

    CLI

    Tell the CLI where Vault is, then log in:

    # Windows PowerShell $env:VAULT_ADDR = “https://:8200″

    # macOS / Linux export VAULT_ADDR=”https://:8200″

    # Log in (paste your token when prompted) vault login

    Note: Vault Enterprise only: if your organization uses namespaces, also set the namespace (ask your Vault administrator which one to use). Leave this out for open source Vault. PowerShell: $env:VAULT_NAMESPACE=”admin/team-a”; Linux/macOS: export VAULT_NAMESPACE=”admin/team-a”.

    Step 3: Enable the Secrets Engines to Discover

    Discovery can only find material in engines that are enabled and hold data. If your PKI, Transit, or KV engines already exist, skip this step. Otherwise, enable the ones you want to scan.

    PKI (certificates)

    1. In the Web UI: go to Secrets Engines, then Enable new engine.
    2. Choose PKI, keep the path pki, click Enable Engine.
    3. Open the engine, then Configure to create or import a CA, then issue certificates as needed.
    vault secrets enable pki
# (example) create a root CA so there is something to discover
vault write pki/root/generate/internal common_name="example.com" ttl=8760h

    Transit (encryption keys)

    1. In the Web UI: Secrets Engines, then Enable new engine, then Transit, path transit, then Enable Engine.
    2. Open the engine, then Create encryption key, then give it a name and type.
    vault secrets enable transit
vault write -f transit/keys/my-app-key   # example key

    KV (key-value secrets)

    1. In the Web UI: Secrets Engines, then Enable new engine, then KV, path secret, then Enable Engine.
    2. Add a secret. Any field containing a certificate or key in PEM text will be discovered.
    vault secrets enable -path=secret kv-v2
vault kv put secret/my-app [email protected]   # example

    Step 4: Create the Read-Only Discovery Policy

    A policy defines what the discovery credential is allowed to do. This one grants only the read and list access needed, nothing more. Adjust the engine paths (pki, transit, secret) to match yours; add extra lines for extra mounts such as pki_int:

    # See which secrets engines are enabled
path "sys/mounts" {
  capabilities = ["read"]
}
# PKI: list and read certificates
path "pki/certs" { capabilities = ["list"] }
path "pki/cert/*" { capabilities = ["read"] }
# Transit: list and read key details (no key material leaves Vault)
path "transit/keys" { capabilities = ["list"] }
path "transit/keys/*" { capabilities = ["read"] }
# KV v2 (mount "secret"): walk and read secrets to find embedded certs/keys
path "secret/metadata/*" { capabilities = ["list", "read"] }
path "secret/data/*" { capabilities = ["read"] }

    In the Web UI: go to Policies, then ACL Policies, then Create ACL policy, name it cbom_discovery, paste the policy text above, and click Create policy. With the CLI, save the text to cbom_discovery_policy.hcl and upload it:

    vault policy write cbom_discovery cbom_discovery_policy.hcl

    Step 5: Set Up Authentication and Get the Credentials

    Discovery signs in to Vault using one of three methods. AppRole is recommended for automated use. Whichever you choose, it must be attached to the cbom_discovery policy from Step 4. This is where the values you will enter into the discovery configuration come from.

    AppRole (recommended)

    AppRole gives you a Role ID (like a username) and a Secret ID (like a password). In the Web UI: Access, then Authentication Methods, then Enable new method, then AppRole, then Enable; create a role named cbom_discovery, add cbom_discovery under Token policies and save; the Role ID is shown on the role overview, and Generate Secret ID creates a Secret ID (copy it immediately, as it is shown once). With the CLI:

    # Enable AppRole (once)
vault auth enable approle
# Create the role bound to the discovery policy
vault write auth/approle/role/cbom_discovery \
  token_policies="cbom_discovery" \
  token_ttl=1h token_max_ttl=4h
# Get the Role ID (stable, safe to reuse)
vault read auth/approle/role/cbom_discovery/role-id
# Generate a Secret ID (treat like a password, copy it now)
vault write -f auth/approle/role/cbom_discovery/secret-id

    Copy the Role ID and the Secret ID.

    Token

    A token is a single secret string. Tokens are most easily generated with the CLI below. In dev mode, the Root Token printed at startup can be used for a quick test. Do not use root tokens in production.

    vault token create -policy="cbom_discovery" -ttl=4h

    Copy the token value (begins with hvs.).

    Username and Password

    In the Web UI: Access, then Authentication Methods, then Enable new method, then Userpass, then Enable; create a user, set a username and password, and add cbom_discovery under Token policies. With the CLI:

    vault auth enable userpass
vault write auth/userpass/users/cbom_discovery \
  password="<strong-password>" \
  token_policies="cbom_discovery"

    Copy the username and password.

    Step 6: Collect Your Connection Values

    Before configuring discovery, gather these:

    • Vault URL: the address of your server, for example https://vault.example.com:8200 (the Api Address from Step 1).
    • Namespace: Vault Enterprise only: from your Vault administrator; leave blank for open source Vault.
    • Authentication method: the method you set up in Step 5: AppRole, Token, or Username and Password.
    • Credentials: AppRole: Role ID plus Secret ID; Token: token; Userpass: username plus password.
    • Engines to scan: any of PKI, Transit, KV (the ones you enabled in Step 3).

    Step 7: Enter the Values in the Discovery Configuration

    In the CBOM platform, create a new HashiCorp Vault discovery task and fill in the form:

    • Vault URL: your Vault address from Step 6 (include https:// and the port).
    • Vault Namespace: Enterprise namespace, or leave empty.
    • Authentication Method: choose AppRole, Token, or Username and Password.
    • AppRole Role ID and Secret ID: AppRole only: the two values copied in Step 5.
    • Vault Token: Token only: the token copied in Step 5.
    • Username and Password: Userpass only: the values from Step 5.
    • Secrets Engines to Scan: select PKI, Transit, and/or KV.
    • Scan Name: a label for this run, for example HashiCorp_Vault_Discovery.

    Save and run the task.

    Step 8: Validate

    After running the discovery task, confirm:

    • The task completes without a permission or authentication error.
    • Certificates from your PKI engine and keys from your Transit engine appear in the inventory.

    You can double-check the credential access directly in Vault using the same account discovery uses:

    # AppRole example: log in, then confirm the paths are readable
vault write auth/approle/login role_id="<ROLE_ID>" secret_id="<SECRET_ID>"
vault list pki/certs
vault list transit/keys
vault kv list secret/

    Common Errors

    • permission denied: the policy is missing a path, or the credential is not attached to cbom_discovery. Fix: check Step 4 again and confirm the auth role or user lists cbom_discovery under token policies.
    • Nothing discovered: the engine names do not match, or the engines are empty. Fix: verify the mount paths (pki, transit, secret) and that they contain material.
    • connection refused or timeout: wrong Vault URL, or Vault not reachable from where discovery runs. Fix: confirm the host, port, and http or https, and use a network-reachable address, not a loopback address.
    • Vault is sealed: Vault was restarted and not unsealed. Fix: run vault operator unseal (Step 1, Option B).
    • AppRole login fails: wrong Role ID or Secret ID, or the Secret ID expired. Fix: generate the Secret ID again (Step 5).
    • TLS or certificate error connecting: the Vault TLS certificate is not trusted by the discovery host. Fix: use a Vault certificate issued by a trusted CA.

    Final Checklist

    • Vault installed, unsealed, and reachable at a known Vault URL.
    • PKI, Transit, and KV engines enabled and holding the material you want discovered.
    • Read-only cbom_discovery policy created.
    • An authentication method set up (AppRole recommended) and attached to the policy.
    • Credentials copied (Role ID plus Secret ID, or Token, or Username plus Password).
    • Values entered in the HashiCorp Vault discovery configuration and the task runs without errors.