HashiCorp Vault Integration

GGScout supports integration with HashiCorp Vault to collect and monitor your secrets. This guide will help you set up and configure the integration.

Supported Features

• KV1 and KV2 secret engines
• Multiple secret versions collection
• Path-based filtering
• Token-based authentication

warning

HashiCorp Vault namespaces are not yet supported

Configuration

To configure GGScout to work with HashiCorp Vault, add the following configuration to your ggscout.toml file:

Token-based Authentication

[sources.vault]
type = "hashicorpvault"
vault_address = "${VAULT_ADDR}"
fetch_all_versions = true
path = "secret/"
mode = "read"

auth.auth_mode = "token"
auth.token = "${VAULT_TOKEN}"

Kubernetes Authentication

[sources.vault]
type = "hashicorpvault"
vault_address = "${VAULT_ADDR}"
fetch_all_versions = true
path = "secret/"
mode = "read"

auth.auth_mode = "k8s"
auth.k8s.service_account = "${KUBERNETES_SERVICE_ACCOUNT}"
auth.k8s.namespace = "${KUBERNETES_NAMESPACE}"
auth.k8s.role = "${KUBERNETES_ROLE}"

Configuration Parameters

Parameter	Description	Required	Default Value
type	Must be set to "hashicorpvault"	Yes
vault_address	The address of your Vault server	Yes
fetch_all_versions	Whether to collect all versions of secrets	Yes
path	Optional path to restrict secret collection	No
auth.auth_mode	Authentication mode (e.g., "token", "k8s")	Yes
mode	Integration mode (one of: "read", "write", "read/write")	No	"read"

With additional parameters depending on the chosen authentication mode:

For Token-based Authentication:

Parameter	Description	Required	Default Value
auth.token	The Vault authentication token	Yes

For Kubernetes Authentication:

Parameter	Description	Required	Default Value
auth.k8s.service_account	The Kubernetes service account	Yes
auth.k8s.namespace	The Kubernetes namespace	Yes
auth.k8s.role	The Kubernetes role	Yes

Environment Variables

• VAULT_ADDR: The address of your Vault server (e.g., http://localhost:8200)

For Token-based Authentication:

• VAULT_TOKEN: Your Vault authentication token

For Kubernetes Authentication:

• KUBERNETES_SERVICE_ACCOUNT: The Kubernetes service account
• KUBERNETES_NAMESPACE: The Kubernetes namespace
• KUBERNETES_ROLE: The Kubernetes role

Required Vault Policies

GGScout requires specific permissions in HashiCorp Vault to collect secrets. The token used for authentication must have the following permissions:

For KV2 Secret Engine

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

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

For KV1 Secret Engine

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

These policies allow GGScout to:

1. List all secrets in the specified path
2. Read the content of each secret
3. Access metadata about the secrets (for KV2)

tip

If you're using a different secret engine path than secret/, adjust the policy paths accordingly.

Best Practices

1. Use environment variables for sensitive values like auth.token
2. Consider using path restrictions to limit the scope of secret collection
3. Enable fetch_all_versions to track changes in your secrets over time
4. Use a dedicated service account with minimal required permissions