HashiCorp Vault Discovery

The Infracast HashiCorp Vault plugin uses the Vault HTTP API to enumerate secrets engine mounts, authentication methods, access control policies, and audit devices. Secret values are never accessed or stored — only the configuration metadata is collected. Authentication is via a Vault token with read-only policy access.

How It Works

1. Infracast authenticates to the Vault API using a token
2. Mounted secrets engines (KV, PKI, AWS, databases, etc.) are enumerated via /sys/mounts
3. Configured auth methods (AppRole, JWT/OIDC, Kubernetes, LDAP, etc.) are listed via /sys/auth
4. ACL policies are discovered and their content captured via /sys/policies/acl
5. Audit device backends (file, syslog, socket) are listed via /sys/audit

Prerequisites

• HTTPS access (TCP/8200 by default) from the Infracast collector to the Vault cluster
• A Vault token with the following capabilities:
  • read on sys/mounts
  • read on sys/auth
  • list and read on sys/policies/acl/*
  • read on sys/audit

warning

Infracast does not need access to any secrets paths (e.g., secret/, kv/, pki/). The discovery token should be tightly scoped to sys/ metadata paths only. Never grant read on secrets data paths.

Creating a Read-Only Vault Policy

Apply the following Vault policy to grant Infracast the minimum required access:

infracast-discovery.hcl

# Enumerate secrets engines
path "sys/mounts" {
  capabilities = ["read"]
}

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

# List and read ACL policies (names and rules only)
path "sys/policies/acl" {
  capabilities = ["list"]
}

path "sys/policies/acl/*" {
  capabilities = ["read"]
}

# List audit devices
path "sys/audit" {
  capabilities = ["read"]
}

# Write the policy to Vault
vault policy write infracast-discovery infracast-discovery.hcl

# Create a token with this policy (periodic token, 90-day TTL)
vault token create \
  -policy=infracast-discovery \
  -display-name=infracast-discovery \
  -period=2160h \
  -no-default-policy

Store the token value securely — you'll need it for the Infracast credential.

tip

Use a periodic token with a renewal cycle that Infracast can keep alive, or an AppRole with short-lived tokens for production deployments. Avoid root tokens — they are not auditable and have no scope restrictions.

Registering the Credential in Infracast

infracast creds add \
  --plugin hashicorp-vault \
  --name "vault-prod" \
  --type vault-token \
  --host "vault.example.com:8200" \
  --vault-token-file /run/secrets/vault-infracast-token \
  --tls-verify true \
  --ca-cert-file /run/secrets/vault-ca.pem

Configuring the Discovery Job

infracast.yaml

discovery:
  jobs:
    - name: hashicorp-vault
      plugin: hashicorp-vault
      credential: vault-prod
      schedule: "0 */6 * * *"   # every 6 hours
      config:
        host: "vault.example.com:8200"
        tls_verify: "true"
        # Optional: Vault namespace (Vault Enterprise only)
        namespace: ""

What Gets Discovered

Resource Type	Description
vault.secrets_engine	Secrets engine mount (path, type: kv/pki/aws/database/etc., description, config, accessor)
vault.auth_method	Authentication method (path, type: approle/jwt/kubernetes/ldap/etc., description, accessor)
vault.policy	ACL policy (name, policy rules document)
vault.audit_device	Audit backend (path, type: file/syslog/socket, description, options)

note

Secret values, keys, leases, and tokens are never collected. Infracast only reads sys/ metadata endpoints which describe the configuration of Vault, not the secrets stored within it.

Troubleshooting

403 Forbidden on API calls

Symptom: Error: Vault API error: 403 Forbidden

Checks:

1. Verify the token is valid and has not expired: vault token lookup
2. Verify the policy grants the required capabilities:

   vault token capabilities sys/mounts
   vault token capabilities sys/auth
   vault token capabilities sys/policies/acl

3. If using Vault Enterprise namespaces, ensure the token is scoped to the correct namespace

Token expiration

Symptom: Discovery stops working with a 403 or permission denied error

Cause: The Vault token has expired.

Fix: Rotate the token:

# Generate a new token with the infracast-discovery policy
vault token create -policy=infracast-discovery -period=2160h -no-default-policy

# Update the Infracast credential
infracast creds update --name "vault-prod" \
  --vault-token-file /run/secrets/new-vault-token

TLS certificate error

Symptom: Error: x509: certificate signed by unknown authority

Fix: Provide the Vault CA certificate:

infracast creds update --name "vault-prod" \
  --ca-cert-file /run/secrets/vault-ca.pem

Or for testing only:

config:
  tls_verify: "false"

Policies missing

Symptom: vault.policy resources are empty

Checks:

1. Verify the token has list capability on sys/policies/acl: vault list sys/policies/acl
2. Default policies (root, default) are excluded from discovery as they are built-in