Déployer et configurer ggscout
Démarrage rapide
Le moyen le plus rapide de tester ggscout est de l'exécuter localement à l'aide du binaire pré-compilé ou du package Python :
Option 1 : Télécharger le binaire (recommandé pour les tests)
Les binaires sont publiés par plateforme à l'adresse https://ggscout-repository.gitguardian.com/ggscout/latest/<target>/ggscout. Choisissez la cible correspondant à votre hôte :
| Plateforme | Cible |
|---|---|
| Linux x86_64, GNU libc | x86_64-unknown-linux-gnu |
| Linux x86_64, musl | x86_64-unknown-linux-musl |
| Linux aarch64 (ARM64), GNU libc | aarch64-unknown-linux-gnu |
| Linux aarch64 (ARM64), musl | aarch64-unknown-linux-musl |
Alpine et les images de conteneur construites dessus sont basées sur musl, elles nécessitent donc une cible musl.
# Download for Linux x86_64 (GNU libc)
wget https://ggscout-repository.gitguardian.com/ggscout/latest/x86_64-unknown-linux-gnu/ggscout
chmod +x ggscout
# Verify installation
./ggscout --help
Les mêmes binaires sont disponibles depuis votre dashboard : lorsque vous configurez une intégration NHI, sélectionnez Install a new scout et utilisez le lien de téléchargement correspondant à votre plateforme.
Option 2 : Utiliser le package Python
# Using uvx (no installation required)
uvx ggscout --help
# Or install with uv
uv tool install ggscout
ggscout --help
Tester avec une configuration simple
Créez un fichier ggscout.toml minimal pour tester la connectivité :
[gitguardian]
api_token = "${GITGUARDIAN_API_KEY}"
endpoint = "https://api.gitguardian.com/v1"
Définissez votre clé API et testez la connexion :
export GITGUARDIAN_API_KEY="your-service-account-token"
./ggscout ping ggscout.toml
En cas de succès, vous êtes prêt à configurer votre première intégration ! Poursuivez votre lecture pour découvrir les options de déploiement en production.
Vue d'ensemble
ggscout peut être exécuté à la demande en tant qu'interface en ligne de commande (CLI) pour les tests et le développement, ou déployé dans votre infrastructure en tant que service autonome pour une utilisation en production :
- Binaire CLI : idéal pour les tests locaux, le développement et les opérations manuelles
- Image Docker : adaptée aux tâches planifiées sur un seul hôte à l'aide de cron
- Kubernetes/Helm : recommandé pour les déploiements en production avec planification et surveillance automatisées
Le déploiement Self-Hosted est fourni avec un chart Helm prêt à l'emploi que vous pouvez utiliser pour déployer ggscout aux côtés de votre instance GitGuardian. Consultez la section Self-hosted dédiée.
Si votre cluster Kubernetes n'a pas d'accès direct à la plateforme GitGuardian SaaS, vous pouvez utiliser GitGuardian Bridge pour établir un tunnel sécurisé entre votre réseau privé et GitGuardian SaaS. Consultez l'exemple ggbridge + ggscout pour des instructions de configuration détaillées.
GitGuardian Scout (ggscout) est un outil en ligne de commande qui agit comme un avant-poste dans le périmètre de votre infrastructure pour collecter et synchroniser des données avec votre plateforme GitGuardian. Il ne stocke ni ne transfère aucune information sensible : les informations sensibles sont toujours hachées à l'aide de l'algorithme HasMySecretLeaked.
Si vous exécutez déjà ggscout, mettez-le à jour vers la version 0.34.1 ou ultérieure. À partir de la version 0.32.0, ggscout classe les valeurs collectées avec le Secrets Detection Engine, afin que l'inventaire NHI puisse afficher le détecteur, la famille de secret, la catégorie et le fournisseur. À partir de la version 0.34.1, il vérifie également chaque secret classé auprès de son fournisseur et rapporte la validité, les permissions, le propriétaire et l'expiration. Téléchargez le binaire le plus récent, ou épinglez l'image Docker et le chart Helm à 0.34.1 ou latest. Consultez Classer les secrets et Vérifier la validité et les permissions à la source.
ggscout prend en charge diverses intégrations avec des gestionnaires de secrets, des systèmes CI/CD et d'autres composants d'infrastructure.
Commandes disponibles
ggscout fournit plusieurs commandes pour gérer vos intégrations :
Commandes GGScout
fetch-and-send- Opération combinée qui récupère les données et les envoie immédiatement à la plateforme GitGuardianfetch- Exécute les fetchers définis dans un fichier de configuration pour collecter des données depuis vos sources, et persiste l'inventaire collecté dans un stockage de fichiers. Ceci ne transfère AUCUNE donnée à GitGuardian.send- Envoie l'inventaire précédemment collecté à votre instance de la plateforme GitGuardiansync-secrets- Récupère les secrets depuis la plateforme GitGuardian et les écrit vers les destinations configuréesping- Teste la connectivité et envoie les informations de source à la plateforme GitGuardian
Flux d'intégration générique
Toutes les intégrations ggscout suivent un schéma cohérent pour les commandes fetch et fetch-and-send :
1. Authentification GitGuardian
Tout d'abord, si vous comptez utiliser une commande autre que fetch, vous devez configurer l'authentification à votre plateforme GitGuardian :
Compte de service GitGuardian
ggscout nécessite des droits d'accès spécifiques pour communiquer avec la plateforme GitGuardian. Créez un compte de service et sélectionnez les scopes pertinents :

nhi:send-inventorypermet à ggscout d'envoyer les données collectées à GitGuardiannhi:write-vaultpermet à ggscout de recevoir des instructions d'écriture de la part de GitGuardian.
Consultez la section Synchronisation des secrets pour en savoir plus.
Exemple de configuration
[gitguardian]
api_token = "${GITGUARDIAN_API_KEY}"
endpoint = "${GITGUARDIAN_API_URL}"
Et définissez ces variables dans votre environnement, par exemple dans un fichier .env :
GITGUARDIAN_API_KEY="your-api-key"
GITGUARDIAN_API_URL="https://api.gitguardian.com/v1"
2. Configuration
Créez un fichier de configuration TOML définissant vos sources et la connexion à la plateforme GitGuardian :
# Source configuration
[sources.my-source]
type = "source_type"
# Source-specific parameters
param1 = "value1"
param2 = "value2"
# GitGuardian platform configuration (required for `fetch-and-send` or `send` commands)
[gitguardian]
api_token = "${GITGUARDIAN_API_KEY}"
endpoint = "${GITGUARDIAN_API_URL}"
# Validity and permissions checks (optional, on by default)
[check]
enabled = true
Consultez Configurer les intégrations pour plus de détails généraux sur le fonctionnement des intégrations.
Configurer les vérifications de validité
À partir de la version 0.34.1, ggscout vérifie chaque secret classé auprès de son fournisseur après la récupération et avant le hachage. La section [check] contrôle cette étape. Chaque clé est facultative.
[check]
enabled = true # false skips the stage
concurrency = 64 # checks run in parallel, capped at 512
timeout_seconds = 10 # per-request timeout, at least 1
total_timeout_seconds = 180 # deadline for the whole stage, 0 means no limit
| Clé | Par défaut | Ce que cela fait |
|---|---|---|
enabled | true | Exécute l'étape de vérification. Définissez-la à false pour vous en désinscrire : les secrets rapportent alors not_checked. |
concurrency | 64 | Nombre de vérifications en cours simultanément. Réduisez-le si les fournisseurs vous limitent le débit. |
timeout_seconds | 10 | Délai d'expiration par requête pour la plupart des analyseurs. Chaque vérification est plafonnée à max(20, 2 × timeout_seconds), nouvelles tentatives incluses. Les analyseurs de code tels qu'AWS et GCP conservent leur propre délai d'expiration. |
total_timeout_seconds | 180 | Délai limite pour l'ensemble de l'étape. Les vérifications encore en attente à l'échéance reviennent avec failed_to_check. 0 supprime la limite. |
Les vérifications s'exécutent dans l'ordre de l'inventaire, de sorte qu'un délai limite trop court pour votre inventaire laisse la même file de secrets en failed_to_check à chaque exécution. Augmentez total_timeout_seconds pour les grands inventaires, et maintenez la récupération plus la vérification en dessous de votre intervalle d'exécution : le chart Helm remplace une exécution encore en cours, et l'exécution remplacée n'envoie rien.
Dans les valeurs Helm, les mêmes clés se placent sous inventory.config.check :
inventory:
config:
check:
enabled: true
total_timeout_seconds: 600
Le journal d'exécution rapporte le résultat par source et au total, par exemple 16 checked: 12 valid, 3 invalid, 1 failed to check; 0 not checked, 40 without checker. Surveillez le décompte failed to check pour repérer un fournisseur que ggscout ne peut pas atteindre. La signification de chaque statut, les vérifications qui font plus que lire, et la façon d'atteindre les fournisseurs auto-hébergés sont décrites dans Vérifier la validité et les permissions à la source.
3. Authentification d'intégration
Configurez l'authentification pour vos intégrations spécifiques à l'aide de variables d'environnement ou d'une configuration directe :
# Additional source-specific environment variables
export HASHICORP_VAULT_TOKEN="your-vault-token"
export AWS_PROFILE="your-aws-profile"
# ... other integration-specific variables
Notez que selon l'intégration, d'autres méthodes d'authentification ne nécessitant pas de secrets à longue durée de vie peuvent être disponibles, telles que :
- Les tokens de compte de service Kubernetes
- Les rôles IAM et OIDC pour les fournisseurs cloud
- L'authentification basée sur les certificats
- Les flux OAuth avec des tokens à courte durée de vie
Consultez la page pertinente dans la section Intégrations pour plus de détails.
4. Exécution
Pour une première utilisation manuelle, vous exécuteriez généralement les commandes suivantes :
pingfetchsend
En production, vous configureriez un cronjob récurrent pour exécuter les commandes ping et fetch-and-send. Consultez la section de déploiement ci-dessous pour plus de détails.
5. Surveillance
Examinez la plateforme GitGuardian pour voir les données collectées et gérer les incidents.
Codes de sortie
ggscout renvoie un code de sortie de processus sur lequel vous pouvez vous appuyer pour la surveillance (cron, ECS/Fargate, Kubernetes) :
| Code de sortie | Signification |
|---|---|
0 | La commande s'est terminée. Pour fetch-and-send, l'inventaire a été envoyé avec succès à GitGuardian. |
| non nul | Une erreur bloquante a arrêté la commande. |
Une commande se termine avec un code non nul en cas d'erreurs bloquantes telles que :
- un fichier de configuration invalide ou illisible ;
- aucune source n'a pu être initialisée (par exemple, l'authentification échoue pour chaque source) ;
- toutes les sources ont échoué à la récupération, donc aucune donnée n'a pu être collectée ;
- l'envoi vers GitGuardian a échoué (
fetch-and-sendetsend).
Les erreurs affectant des secrets, chemins ou points de montage individuels sont non bloquantes : elles sont journalisées et l'exécution se poursuit avec le reste des données, puis envoie ce qu'elle a pu collecter. Par exemple, un token qui manque de permission sur un chemin produit :
ERROR ... step="list keys": task errored error=Failed to list mount keys for mount kv2 kv_app ...
Cela ne fait pas échouer la commande — fetch-and-send téléverse quand même les autres secrets et se termine avec 0.
Comme les échecs partiels sont non bloquants, le code de sortie seul ne vous indique pas si ggscout a collecté moins de secrets que prévu. Un token qui perd l'accès à un point de montage entier peut toujours se terminer avec 0 et un inventaire plus petit (ou vide). Pour une surveillance complète, surveillez également :
- les lignes de journal contenant
task erroredou100% failure rate, et - le nombre d'éléments collectés (
Fetched a total of N items) ou la taille de l'inventaire sur la plateforme GitGuardian.
Déploiement
Une fois ggscout configuré, vous pouvez le déployer à l'aide de diverses méthodes selon les besoins de votre infrastructure.
Docker
Pour les déploiements en production sur un seul hôte ou lorsque vous avez besoin d'une exécution planifiée sans Kubernetes, utilisez l'image Docker avec une tâche cron.
GitGuardian fournit une image docker publique sur GitHub Container Registry : ghcr.io/gitguardian/ggscout/chainguard.
Les exemples suivants utilisent le tag latest, mais vous pouvez épingler une version spécifique pour une utilisation en production.
Consultez la liste des versions disponibles pour choisir une version.
Pourquoi Chainguard ?
L'image Docker ggscout est construite à l'aide des images de base distroless de Chainguard pour une sécurité maximale :
- Zéro CVE : les images Chainguard sont continuellement reconstruites depuis les sources dans des environnements sécurisés, éliminant les vulnérabilités connues
- Surface d'attaque minimale : contient uniquement le binaire ggscout et les bibliothèques d'exécution essentielles - aucun shell, gestionnaire de paquets ni outil de débogage
- Sécurisé par conception : s'exécute en tant qu'utilisateur nonroot (UID 65532) et suit les principes distroless
Contenu de l'image :
- Couche de base :
cgr.dev/chainguard/glibc-dynamic:latest- bibliothèques d'exécution minimales - Couche applicative : binaire ggscout (écrit en Rust) à
/usr/bin/ggscout - Couche de configuration : utilisateur nonroot et point d'entrée sécurisé
Ce qui N'EST PAS inclus (pour la sécurité) :
- Aucun shell (
/bin/sh,/bin/bash) - Aucun gestionnaire de paquets (
apt,yum,apk) - Aucun utilitaire de débogage ni éditeur de texte
- Aucun utilitaire système au-delà des bibliothèques d'exécution essentielles
Cette approche réduit considérablement la surface d'attaque du conteneur et élimine des classes entières de vulnérabilités.
Vous pouvez exécuter manuellement l'image à l'aide des commandes suivantes :
# Ping command
docker run --rm -ti -v ${PWD}:/tmp --env-file .env ghcr.io/gitguardian/ggscout/chainguard:latest ping /tmp/config.toml
# Fetch and send command
docker run --rm -ti -v ${PWD}:/tmp --env-file /path/to/config/dir/.env ghcr.io/gitguardian/ggscout/chainguard:latest fetch-and-send /tmp/config.toml
L'image Docker embarque la CLI.
Configurez une crontab pour mettre en place une tâche récurrente avec les commandes que vous devez lancer.
Vous trouverez ci-dessous un exemple d'exécution avec crontab.
# Ping command (every minute)
* * * * * docker run --rm -ti -v /path/to/config/dir:/tmp --env-file /path/to/config/dir/.env ghcr.io/gitguardian/ggscout/chainguard:latest ping /tmp/config.toml
# Fetch and send command (every 5 minutes)
*/5 * * * * docker run --rm -ti -v /path/to/config/dir:/tmp --env-file /path/to/config/dir/.env ghcr.io/gitguardian/ggscout/chainguard:latest fetch-and-send /tmp/config.toml
Remplacez le /path/to/config/dir par l'emplacement où vous avez configuré votre fichier de configuration et votre fichier .env.
Exemple de .env :
GITGUARDIAN_API_KEY=my_gitguardian_api_key
GITLAB_TOKEN=my_gitlab_token
HASHICORP_VAULT_TOKEN=my_vault_token
Helm
Vous pouvez déployer ggscout sur un cluster Kubernetes à l'aide du chart Helm ggscout.
Il s'agit du modèle de déploiement préféré si vous exécutez ggscout en tant que collecteur autonome de manière périodique.
Les instructions de déploiement sont disponibles sur notre dépôt GitHub public.
Les valeurs Helm vous permettent de définir la configuration de ggscout en YAML. Des exemples sont fournis sous forme de modèles dans le dépôt.
Déploiement sur OpenShift
ggscout prend en charge le déploiement sur les plateformes OpenShift. Lors du déploiement sur OpenShift, vous devez désactiver le contexte de sécurité par défaut dans la configuration du chart Helm.
Ajoutez la configuration suivante à votre values.yaml Helm :
securityContext:
# Enable security Context in deployments.
# Set to false when deploying on OpenShift
enabled: false
Cette configuration est nécessaire car OpenShift possède ses propres contraintes de contexte de sécurité qui entrent en conflit avec les paramètres de contexte de sécurité Kubernetes par défaut.
Toutes les autres options de configuration pour les sources, l'authentification et la planification restent les mêmes lors du déploiement sur OpenShift.