Déployer et configurer ggscout

Démarrage rapide

Le moyen le plus rapide de tester ggscout est de l'exécuter localement en utilisant le binaire pré-compilé ou le package Python :

Option 1 : Télécharger le binaire (recommandé pour les tests)

# 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

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

Si l'opération réussit, vous êtes prêt à configurer votre première intégration ! Poursuivez la 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 comme service autonome pour un usage 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 hôte unique via cron
• Kubernetes/Helm : recommandé pour les déploiements en production avec planification et surveillance automatisées

ggscout est compatible avec les instances GitGuardian Self-Hosted !

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.

Vous utilisez ggscout avec GitGuardian SaaS derrière un réseau privé ?

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.

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 GitGuardian
• fetch - 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. Cela ne transfère AUCUNE donnée vers GitGuardian.
• send - Envoie l'inventaire précédemment collecté vers votre instance de la plateforme GitGuardian
• sync-secrets - Récupère les secrets depuis la plateforme GitGuardian et les écrit vers les destinations configurées
• ping - Teste la connectivité et envoie les informations sur la 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 prévoyez d'utiliser une commande autre que fetch, vous devez configurer l'authentification vers 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 appropriés :

• nhi:send-inventory permet à ggscout d'envoyer les données collectées vers GitGuardian
• nhi:write-vault permet à ggscout de recevoir des instructions d'écriture depuis 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}"

Consultez Configurer les intégrations pour plus de détails généraux sur le fonctionnement des intégrations.

3. Authentification des intégrations

Configurez l'authentification pour vos intégrations spécifiques à l'aide de variables d'environnement ou directement dans la configuration :

# Additional source-specific environment variables
export HASHICORP_VAULT_TOKEN="your-vault-token"
export AWS_PROFILE="your-aws-profile"
# ... other integration-specific variables

Notez qu'en fonction de l'intégration, d'autres méthodes d'authentification peuvent être disponibles qui ne nécessitent pas de secrets à longue durée de vie, telles que :

• Tokens de compte de service Kubernetes
• Rôles IAM et OIDC pour les fournisseurs de cloud
• Authentification par certificat
• Flux OAuth avec tokens à courte durée de vie

Consultez la page correspondante 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 :

• ping
• fetch
• send

En production, vous configureriez un cronjob récurrent pour exécuter les commandes ping et fetch-and-send. Consultez la section déploiement ci-dessous pour plus de détails.

5. Surveillance

Consultez 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é à récupérer les données, donc aucune donnée n'a pu être collectée ;
• l'envoi vers GitGuardian a échoué (fetch-and-send et send).

Les erreurs affectant des secrets, chemins ou mounts 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 n'a pas la 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 tout de même les autres secrets et se termine avec le code 0.

attention

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 mount entier peut tout de même se terminer avec le code 0 avec un inventaire plus petit (ou vide). Pour une surveillance complète, surveillez également :

• les lignes de log contenant task errored ou 100% 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 en utilisant diverses méthodes selon les besoins de votre infrastructure.

Docker

Pour les déploiements en production sur un hôte unique 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 un usage en production.
Consultez la liste des versions disponibles pour choisir une version.

Pourquoi Chainguard ?

L'image Docker de ggscout est construite en utilisant les 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 - pas de shell, gestionnaires de packages ou outils de débogage
• Sécurisé par conception : s'exécute en tant qu'utilisateur nonroot (UID 65532) et suit les principes distroless

Ce qui se trouve à l'intérieur de l'image :

1. Couche de base : cgr.dev/chainguard/glibc-dynamic:latest - bibliothèques d'exécution minimales
2. Couche d'application : binaire ggscout (écrit en Rust) à /usr/bin/ggscout
3. Couche de configuration : utilisateur nonroot et point d'entrée sécurisé

Ce qui n'est PAS inclus (pour la sécurité) :

• Pas de shell (/bin/sh, /bin/bash)
• Pas de gestionnaires de packages (apt, yum, apk)
• Pas d'utilitaires de débogage ni d'éditeurs de texte
• Pas d'utilitaires 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 en utilisant les 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

Utilisez une crontab pour configurer une tâche récurrente

L'image Docker embarque le CLI.
Configurez une crontab pour définir une tâche récurrente avec les commandes que vous devez lancer.

Voici 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 en utilisant le chart Helm de ggscout.

astuce

C'est le modèle de déploiement préféré si vous exécutez ggscout comme 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 comme modèles dans le dépôt.

Déploiement 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 a ses propres contraintes de contexte de sécurité qui entrent en conflit avec les paramètres par défaut du contexte de sécurité Kubernetes.

info

Toutes les autres options de configuration pour les sources, l'authentification et la planification restent les mêmes lors du déploiement sur OpenShift.