Déployer et configurer ggscout

Démarrage rapide

La manière la 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)

# 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 cela fonctionne, vous êtes prêt à configurer votre première intégration ! Continuez la lecture pour 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 la production :

• Binaire CLI : idéal pour les tests locaux, le développement et les opérations manuelles
• Image Docker : adaptée aux jobs planifiés sur un seul hôte avec 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 livré avec un Helm chart 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.

Utilisation de 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. Voir l'exemple ggbridge + ggscout pour les instructions détaillées.

GitGuardian Scout (ggscout) est un outil en ligne de commande qui agit comme un avant-poste dans votre périmètre d'infrastructure pour collecter et synchroniser des données avec votre plateforme GitGuardian. Il ne stocke et ne transfère aucune information sensible — celles-ci sont toujours hachées avec l'algorithme HasMySecretLeaked.

ggscout prend en charge diverses intégrations avec des Secrets Managers, 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 les données depuis vos sources, et persiste l'inventaire collecté dans un stockage de fichiers. Cela ne transfère AUCUNE donnée à GitGuardian.
• send — envoie un inventaire précédemment collecté à votre instance de plateforme GitGuardian
• sync-secrets — récupère des secrets depuis la plateforme GitGuardian et les écrit vers les destinations configurées
• ping — 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 :

Service Account GitGuardian

ggscout requiert des droits d'accès spécifiques pour communiquer avec la plateforme GitGuardian. Créez un service account et sélectionnez les scopes pertinents :

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

Voir Configurer les intégrations pour plus de détails sur le fonctionnement des intégrations.

3. Authentification de l'intégration

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 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 :

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

Consultez la page correspondante de la section Intégrations pour plus de détails.

4. Exécution

Pour une première utilisation manuelle, vous exécuterez généralement les commandes suivantes :

• ping
• fetch
• send

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

5. Surveillance

Examinez la plateforme GitGuardian pour voir les données collectées et gérer les incidents.

Déploiement

Une fois ggscout configuré, vous pouvez le déployer selon différentes méthodes en fonction des 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 un cron job.

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 vous fixer sur une version spécifique pour la production.
Consultez la liste des releases disponibles pour choisir une version.

Pourquoi Chainguard ?

L'image Docker ggscout est construite sur les images de base distroless de Chainguard pour une sécurité maximale :

• Zéro CVE : les images Chainguard sont reconstruites en continu depuis la source dans des environnements sécurisés, éliminant les vulnérabilités connues
• Surface d'attaque minimale : ne contient que le binaire ggscout et les bibliothèques d'exécution essentielles — pas de shell, gestionnaire de paquets 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 est dans l'image :

1. Couche de base : cgr.dev/chainguard/glibc-dynamic:latest — bibliothèques d'exécution minimales
2. Couche application : binaire ggscout (écrit en Rust) à /usr/bin/ggscout
3. Couche configuration : utilisateur nonroot et entrypoint 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 avec 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 un crontab pour configurer un job récurrent

L'image Docker embarque la CLI.
Configurez un crontab pour mettre en place un job récurrent avec les commandes que vous souhaitez 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 /path/to/config/dir par le chemin où vous avez placé 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 via le Helm chart ggscout.

astuce

C'est le modèle de déploiement préféré si vous exécutez ggscout en tant que collecteur autonome 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 templates dans le dépôt.

Déploiement OpenShift

ggscout prend en charge le déploiement sur des plateformes OpenShift. Lors du déploiement sur OpenShift, vous devez désactiver le security context par défaut dans la configuration du Helm chart.

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 dispose de ses propres contraintes de security context qui entrent en conflit avec les paramètres par défaut de Kubernetes.

info

Toutes les autres options de configuration pour les sources, l'authentification et la planification restent identiques lors d'un déploiement sur OpenShift.