Intégration HashiCorp Vault

GGScout prend en charge l'intégration avec HashiCorp Vault pour collecter et surveiller vos secrets, à la fois Vault Community Edition et Vault Enterprise (self-hosted et HashiCorp Cloud Dedicated). Ce guide vous aide à mettre en place et configurer l'intégration.

Fonctionnalités prises en charge

Disponibles sur toutes les éditions (Community et Enterprise) :

• Engines de secrets KV1 et KV2
• Collecte de plusieurs versions de secrets
• Filtrage par chemin
• Authentification par token

Disponibles uniquement sur Vault Enterprise et HashiCorp Cloud Dedicated (HCD) :

• Prise en charge des namespaces

Prise en charge HashiCorp Cloud Dedicated

GGScout prend pleinement en charge les environnements HashiCorp Cloud Dedicated (HCD). Lors de l'utilisation de HCD, les namespaces sont automatiquement inclus dans le resource_id exporté, suivant le schéma de l'API Vault décrit dans la documentation HashiCorp.

Filtrage par namespace

Restriction de l'accès aux namespaces (Enterprise et HCD uniquement)

Les namespaces sont une fonctionnalité de Vault Enterprise et HCD. Avec ces éditions, vous pouvez limiter les namespaces auxquels ggscout accède via le paramètre de configuration namespaces :

[sources.vault]
type = "hashicorpvault"
vault_address = "${VAULT_ADDR}"
fetch_all_versions = true
namespaces = ["admin", "prod", "shared"]  # Only fetch from these namespaces

info

Si le paramètre namespaces n'est pas spécifié, ggscout récupèrera les secrets depuis tous les namespaces accessibles. Utilisez ce paramètre pour limiter le périmètre de collecte de secrets et améliorer les performances.

Filtrage au niveau ressource

Vous pouvez également filtrer les secrets par namespace directement dans vos motifs include/exclude. Le namespace devient une partie du chemin de la ressource, permettant un filtrage précis :

# Include all secrets from the 'admin' namespace, 'kv' mount, under 'my_app' path
[[sources.vault.include]]
resource_ids = ["admin/kv/my_app/*"]

# Include secrets from multiple namespaces
[[sources.vault.include]]
resource_ids = ["admin/kv/*", "dev/secrets/*", "prod/database/*"]

# Exclude test secrets from all namespaces
[[sources.vault.exclude]]
resource_ids = ["*/test/*", "*/temp/*"]

Le filtrage fonctionne de manière transparente avec la structure de namespaces, où le format de resource_id suit : namespace/mount/path

Configuration

Pour configurer GGScout afin qu'il fonctionne avec HashiCorp Vault, ajoutez la configuration suivante à votre fichier ggscout.toml :

Authentification par token

[sources.vault]
type = "hashicorpvault"
vault_address = "${VAULT_ADDR}"
fetch_all_versions = true
mode = "read"
env = "production"
owner = "devops-team@example.com"

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

# Optional: Limit to specific namespaces (Vault Enterprise and HCD only)
namespaces = ["admin", "prod", "shared"]

# Standard filtering (works on all editions including Vault Community Edition)
[[sources.vault.include]]
resource_ids = ["app/*", "database/*", "api-key"]

# Namespace-aware filtering (Vault Enterprise and HCD only)
[[sources.vault.include]]
resource_ids = ["admin/kv/my_app/*", "prod/secrets/database/*"]

[[sources.vault.exclude]]
resource_ids = ["*/test/*", "*/temp/*", "dev/old-secret"]

Configuration HashiCorp Cloud Dedicated

Pour les environnements HashiCorp Cloud Dedicated, la configuration est identique, mais le filtrage fonctionne automatiquement avec les namespaces :

[sources.vault_hcd]
type = "hashicorpvault"
vault_address = "${HCD_VAULT_ADDR}"
fetch_all_versions = true
mode = "read"
env = "production"
owner = "devops-team@example.com"

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

# Optional: Limit to specific namespaces
namespaces = ["admin", "prod", "shared"]

# Namespace-specific filtering
[[sources.vault_hcd.include]]
resource_ids = [
    "admin/kv/my_app/*",           # All secrets in admin namespace, kv mount, my_app path
    "prod/database/credentials/*", # Database credentials in prod namespace
    "shared/api-keys/*"            # Shared API keys across teams
]

[[sources.vault_hcd.exclude]]
resource_ids = [
    "*/test/*",                    # Exclude test secrets from all namespaces
    "dev/temp/*",                  # Exclude temporary secrets in dev namespace
    "*/legacy/*"                   # Exclude legacy secrets from all namespaces
]

Authentification Kubernetes

[sources.vault]
type = "hashicorpvault"
vault_address = "${VAULT_ADDR}"
fetch_all_versions = true
mode = "read"
env = "production"
owner = "devops-team@example.com"

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

[[sources.vault.include]]
resource_ids = ["app/*", "database/*", "api-key"]

[[sources.vault.exclude]]
resource_ids = ["test/*", "temp/*", "old-secret"]

Paramètres de configuration

Paramètre	Description	Requis	Valeur par défaut
type	Doit être défini sur "hashicorpvault"	Oui
vault_address	L'adresse de votre serveur Vault	Oui
fetch_all_versions	Indique s'il faut collecter toutes les versions des secrets	Oui
namespaces	Liste des namespaces Vault depuis lesquels récupérer les secrets (Vault Enterprise et HCD uniquement). Si non spécifié, récupère depuis tous les namespaces accessibles	Non	Tous les namespaces accessibles
auth.auth_mode	Mode d'authentification (par ex. « token », « k8s »)	Oui
mode	Mode d'intégration (parmi : « read », « write », « read/write »)	Non	"read"
env	Libellé d'environnement pour catégoriser les secrets (par ex. « production », « staging », « development »)	Non
owner	Propriétaire de cette source (un e-mail, généralement d'un employé ou d'une équipe)	Non
[[sources.<name>.include]]	Table de motifs de resource_id à inclure (voir ci-dessous)	Non
[[sources.<name>.exclude]]	Table de motifs de resource_id à exclure (voir ci-dessous)	Non

Avec des paramètres supplémentaires selon le mode d'authentification choisi :

Pour l'authentification par token :

Paramètre	Description	Requis	Valeur par défaut
auth.token	Le token d'authentification Vault	Oui

Pour l'authentification Kubernetes :

Paramètre	Description	Requis	Valeur par défaut
auth.k8s.service_account	Le service account Kubernetes	Oui
auth.k8s.namespace	Le namespace Kubernetes	Oui
auth.k8s.role	Le rôle Kubernetes	Oui

Variables d'environnement

• VAULT_ADDR : l'adresse de votre serveur Vault (par ex. http://localhost:8200)

Pour l'authentification par token :

• VAULT_TOKEN : votre token d'authentification Vault

Pour l'authentification Kubernetes :

• KUBERNETES_SERVICE_ACCOUNT : le service account Kubernetes
• KUBERNETES_NAMESPACE : le namespace Kubernetes
• KUBERNETES_ROLE : le rôle Kubernetes

Policies Vault requises

GGScout requiert des permissions spécifiques dans HashiCorp Vault pour collecter les secrets. Le token utilisé pour l'authentification doit avoir les permissions suivantes :

Pour l'engine de secrets KV2

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

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

Ces policies permettent à GGScout de :

1. Lister tous les secrets dans le(s) chemin(s) spécifié(s)
2. Lire le contenu de chaque secret
3. Accéder aux métadonnées des secrets

Pour l'engine de secrets KV1

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

Cette policy permet à GGScout de :

1. Lister tous les secrets dans le(s) chemin(s) spécifié(s)
2. Lire le contenu de chaque secret

Pour HashiCorp Cloud Dedicated et Enterprise (avec namespaces)

Lors de l'utilisation de HCD ou Vault Enterprise avec namespaces, les policies sont scopées au namespace dans lequel elles sont créées. Chaque namespace a son propre espace de policy, et vous créez des policies dans des namespaces spécifiques plutôt que d'utiliser des wildcards pour matcher entre namespaces.

Pour des policies spécifiques à un namespace, vous créeriez des policies dans chaque namespace :

# Policy created within the 'admin' namespace for KV2 secrets
path "kv/data/*" {
  capabilities = ["read", "list"]
}

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

# Policy for specific paths within a namespace using the + wildcard
path "kv/data/my_app/+/config" {
  capabilities = ["read", "list"]
}

path "kv/metadata/my_app/+/config" {
  capabilities = ["read", "list"]
}

info

Lorsque vous travaillez avec des namespaces, les policies sont créées et gérées dans le scope de chaque namespace. Le caractère wildcard + peut être utilisé dans les segments de chemin comme documenté dans la documentation des Policies HashiCorp Vault, mais les wildcards de policy entre namespaces ne sont pas pris en charge. Pour plus d'informations sur les namespaces, consultez la documentation des Namespaces HashiCorp Vault.

Bonnes pratiques

1. Utilisez des variables d'environnement pour les valeurs sensibles comme auth.token
2. Tirez parti du filtrage par namespace dans les environnements Vault Enterprise et HCD pour contrôler précisément quels secrets sont collectés
3. Envisagez d'utiliser des restrictions par chemin pour limiter le périmètre de collecte de secrets
4. Activez fetch_all_versions pour suivre les changements dans vos secrets au fil du temps
5. Utilisez un service account dédié avec le minimum de permissions nécessaires
6. Pour les environnements HCD, profitez de l'inclusion automatique du namespace dans les resource_ids pour un filtrage fin
7. Utilisez des motifs wildcard comme */test/* pour exclure les secrets de test entre tous les namespaces