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:

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

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

Configuration Parameters

Parameter	Description	Required
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	No
path	Optional path to restrict secret collection	No
auth.auth_mode	Authentication mode (e.g., "token")	Yes
auth.token	The Vault authentication token	Yes

Environment Variables

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

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