Safeguard Docs
Credentials VaultProviders

HashiCorp Vault

Read scan credentials from HashiCorp Vault KV v1 or v2 and dynamic secrets engines, with token, AppRole or Kubernetes sign-in, and lease revocation at scan end.

HashiCorp Vault

Reference

vault://<mount>/<path>#<key>
pam://hashicorp-vault/<mount>/<path>#<key>
  • KV version 2: include data/ after the mount, for example vault://secret/data/scanning/dast#password. The runner reads GET /v1/secret/data/scanning/dast and returns the password key of the current version.
  • KV version 1: vault://kv/scanning/dast#password.
  • Dynamic secrets (database, cloud and other engines that generate a credential): vault://database/creds/scan-readonly#password, and vault://database/creds/scan-readonly#username for the user name. Within one scan both come from a single read, so the user name and password belong to the same generated credential.
  • #<key> may be left out only when the secret has exactly one key. A key that holds a number or an object is returned as JSON text.

What the Vault administrator prepares

A policy that grants read on the scan paths only, for example:

path "secret/data/scanning/*" {
  capabilities = ["read"]
}
# Only for dynamic secrets: let the runner end the leases it created.
path "sys/leases/revoke" {
  capabilities = ["update"]
}

and one of these sign-in methods for the runner:

authWhat the runner sendsSettings
token (default)X-Vault-Token from the token setting. A configured token is never revoked by the runner.token: file:///etc/safeguard/vault-token
approlePOST /v1/auth/<auth_mount>/login with role_id and secret_id. Bind the role to the runner's address with secret_id_bound_cidrs and token_bound_cidrs.role_id, secret_id, auth_mount (default approle)
kubernetesPOST /v1/auth/<auth_mount>/login with the pod's service account token, for a runner in Kubernetes.role, jwt_path (default the pod's token), auth_mount (default kubernetes)

A token from a login is kept in memory, renewed shortly before its lease ends or once on a 403, and revoked (auth/token/revoke-self) when the scan ends.

Runner configuration

providers:
  - type: hashicorp-vault
    url: https://vault.example.internal:8200
    auth: approle
    role_id: env://VAULT_ROLE_ID          # a literal role id is accepted too
    secret_id: file:///etc/safeguard/vault-secret-id
    namespace: security                   # Vault Enterprise namespace, optional
    ca_cert: /etc/safeguard/internal-root-ca.pem
    revoke_leases: true                   # default
    allowed_refs:
      - "secret/data/scanning/*"
      - "database/creds/scan-readonly"

A Vault agent on the runner machine can be used too: point url at the agent's local listener (for example http://127.0.0.1:8100, plain http is accepted for this machine only) and use auth: token with the agent's sink file.

Leases of dynamic secrets

When a read returns a lease (dynamic secrets), the runner revokes that lease when the scan ends (PUT /v1/sys/leases/revoke), so the generated database or cloud credential does not stay valid for its whole TTL. The policy must allow update on sys/leases/revoke; if it does not, the credential simply expires at the end of its lease and the runner logs a warning. Set revoke_leases: false to leave leases alone. KV secrets have no lease and are not affected.

Errors

Vault answerCode
403 after a fresh sign-inFORBIDDEN: the policy does not grant read on the path
404, or a KV v2 version that is deletedNOT_FOUND: check the mount, path and data/
AppRole or Kubernetes login refusedAUTH_FAILED
Key not in the secretNOT_FOUND

On this page