Déployer ggshield à grande échelle avec un token de service account

Utilisez cette page pour déployer Machine Scan sur des endpoints managés et téléverser les inventaires de scan vers GitGuardian selon une planification. Le même modèle fonctionne avec Jamf Pro, Kandji, Intune, Workspace ONE, Mosyle, Addigy, Canonical Landscape, ou des outils de gestion de configuration tels que Ansible, Puppet, Chef et Salt.

Modèle de déploiement

Gardez le déploiement sous forme de jobs MDM distincts. Cela rend chaque partie facile à auditer, réparer et annuler. Le job de plantation de honeytoken est facultatif, et le scan et la protection par honeytoken peuvent être déployés indépendamment l'un de l'autre.

Job	Ce qu'il fait	Token GitGuardian	Bon usage MDM
Installer ou mettre à jour ggshield	Déployer le binaire CLI	Non requis	déploiement de package ou script de remédiation
Installer ou mettre à jour machine_scan	Ajouter le plugin Machine Scan pour l'utilisateur de scan	Uniquement pour installer par nom	script d'audit/remédiation
Scan d'inventaire	Exécuter ggshield machine report	Requis	script planifié, une fois par jour
Plantation de honeytoken	Exécuter ggshield honeytoken plant	Requis	script planifié, hebdomadaire ou intégré au scan quotidien

En termes MDM, un script d'audit vérifie si une machine est conforme ; un script de remédiation installe ou répare ce qui manque.

Étape 1 - Créer le token

Créez un token dédié de Service Account avec les scopes scan, honeytokens:check et endpoints:send. Un seul token couvre à la fois l'installation du plugin (lorsque vous installez par nom) et le téléversement quotidien de l'inventaire. Ajoutez honeytokens:write si vous plantez également des honeytokens.

Scope	Pourquoi il est nécessaire
scan	Exécuter le scan et installer le plugin machine_scan par nom
honeytokens:check	Reconnaître vos honeytokens au lieu de les déclencher
endpoints:send	Téléverser l'inventaire de la machine vers votre workspace
honeytokens:write	Planter des honeytokens sur la machine. Nécessaire uniquement pour la protection par honeytoken

Utilisez un token de Service Account dédié (pas un token personnel) et n'exécutez pas ggshield auth login sur les machines de la flotte. Si vous préparez un package de plugin signé ou interne au lieu d'installer par nom, le job d'installation n'a besoin d'aucun token.

Stockez le token dans votre coffre de secrets MDM ou gestionnaire de secrets, et injectez-le uniquement au moment de l'exécution.

Durcissement facultatif : diviser en deux tokens

endpoints:send et honeytokens:write sont les scopes qui écrivent dans votre workspace, ce sont donc ceux à contenir. Les jobs de téléversement et de plantation sont des jobs planifiés, mais le job d'installation/mise à jour s'exécute sur chaque machine et est bien plus exposé. Donnez au job d'installation/mise à jour un token limité à scan et réservez les scopes d'écriture aux jobs planifiés : un token d'installation compromis ne peut alors pas pousser un inventaire falsifié, masquer des découvertes dans votre dashboard, ni planter des honeytokens. Le coût est un secret supplémentaire à faire tourner. Si vous installez le plugin à partir d'un package préparé plutôt que par nom, le job d'installation n'a besoin d'aucun token, donc un token unique pour les jobs planifiés respecte déjà le principe du moindre privilège.

Étape 2 - Installer et gérer ggshield

Utilisez la méthode de déploiement à laquelle votre flotte fait déjà confiance :

• Jamf Pro / Kandji / Mosyle / Addigy : déployez le package macOS signé ou exécutez un script de remédiation d'installation.
• Intune : déployez l'installeur Windows ou exécutez l'installeur PowerShell ; pour macOS/Linux, utilisez des scripts shell ou des remédiations.
• Workspace ONE / outils RMM : utilisez un package managé ou une affectation de script.
• Landscape / Ansible / Puppet / Chef / Salt : installez le .deb/.rpm ou exécutez l'installeur officiel, puis imposez la version.

Pour les déploiements macOS/Linux basés sur des scripts, installez d'abord uniquement le binaire :

curl -sSfL https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.sh | bash -s -- --install-only

Auditez avec :

ggshield --version   # must be >= 1.51.0 to install machine_scan by name

Pour les grandes flottes, préférez un cache de package interne ou un package hébergé par le MDM afin que chaque machine ne télécharge pas depuis Internet en même temps.

Étape 3 - Installer Machine Scan pour l'utilisateur de scan

Le scan de machine doit être installé et activé avant d'exécuter ggshield machine report. Le plugin est limité à l'utilisateur, installez-le donc pour l'utilisateur qui exécutera le scan (généralement l'utilisateur connecté sur les postes de travail, ou un utilisateur cible dédié sur les serveurs).

Si votre MDM peut préparer un package de plugin signé/interne, installez ce package et aucun token GitGuardian n'est nécessaire pour le job d'installation :

sudo -i -u "$TARGET_USER" -- ggshield plugin install /path/to/machine-scan-plugin.whl

Si vous installez par nom, ggshield plugin install machine_scan nécessite ggshield 1.51.0 ou version ultérieure et contacte le catalogue de plugins GitGuardian. Injectez le token de service account au moment de l'exécution ; ne le stockez pas avec ggshield auth login sur l'endpoint. Pour les instances UE ou Self-Hosted, exportez GITGUARDIAN_INSTANCE dans le même shell.

Exemple macOS pour les scripts de type Jamf/Kandji :

loggedInUser=$(scutil <<< "show State:/Users/ConsoleUser" | awk '/Name :/ && !/loginwindow/ {print $3}')

# Your MDM injects the service account token as GGSHIELD_SAT.
printf '%s\n' "$GGSHIELD_SAT" | sudo -i -u "$loggedInUser" -- /bin/zsh -c \
  'IFS= read -r GITGUARDIAN_API_KEY && export GITGUARDIAN_API_KEY && exec ggshield plugin install machine_scan < /dev/null'

sudo -i -u "$loggedInUser" -- ggshield plugin list

Exemple Linux :

# Your MDM injects the service account token as GGSHIELD_SAT.
printf '%s\n' "$GGSHIELD_SAT" | sudo -i -u "$TARGET_USER" -- /bin/bash -c \
  'IFS= read -r GITGUARDIAN_API_KEY && export GITGUARDIAN_API_KEY && exec ggshield plugin install machine_scan < /dev/null'

sudo -i -u "$TARGET_USER" -- ggshield plugin list

Auditez le succès lorsque ggshield plugin list affiche machine_scan pour l'utilisateur de scan.

Étape 4 - Exécuter le scan d'inventaire quotidien

Planifiez un job MDM par jour qui injecte le token de service account au moment de l'exécution et exécute ggshield machine report en tant qu'utilisateur de scan (report scanne et envoie en une seule étape ; voir Commandes).

# Your MDM injects the service account token as GGSHIELD_SAT.
printf '%s\n' "$GGSHIELD_SAT" | sudo -i -u "$loggedInUser" -- /bin/zsh -c \
  'IFS= read -r GITGUARDIAN_API_KEY && export GITGUARDIAN_API_KEY && exec ggshield machine report < /dev/null'

Pour Linux, utilisez /bin/bash et votre utilisateur cible. Pour les instances UE ou Self-Hosted, exportez également GITGUARDIAN_INSTANCE dans le même shell.

Ce modèle garde le token hors des arguments de ligne de commande, des fichiers, des logs et de ggshield auth login. C'est important car les malwares de supply-chain scrutent couramment les postes de travail à la recherche d'identifiants dans les fichiers, les environnements shell et les configurations de gestionnaire de packages. Désactivez le traçage du shell (set -x) dans les scripts qui manipulent le token.

Si votre MDM ne peut pas exécuter de scripts planifiés de manière fiable, vous pouvez utiliser launchd ou un timer systemd en solution de repli. Gardez le token dans un fichier accessible uniquement à root et supprimez-le lors de la désinstallation.

Étape 5 - Planter des honeytokens (facultatif)

La protection par honeytoken est indépendante du scan. ggshield honeytoken plant réconcilie la machine avec GitGuardian à chaque exécution : il écrit ou rafraîchit le profil d'identifiants leurres pour les honeytokens actifs et supprime le profil pour ceux qui ont été révoqués, sans toucher à aucun autre profil d'identifiants.

# Your MDM injects the service account token as GGSHIELD_SAT.
printf '%s\n' "$GGSHIELD_SAT" | sudo -i -u "$loggedInUser" -- /bin/zsh -c \
  'IFS= read -r GITGUARDIAN_API_KEY && export GITGUARDIAN_API_KEY && exec ggshield honeytoken plant < /dev/null'

Planifiez-le soit dans le job d'inventaire quotidien, soit comme son propre job à une fréquence plus basse. L'état souhaité change bien moins souvent que les résultats de scan, donc un passage hebdomadaire suffit généralement sur les grandes flottes. Comme la commande réconcilie plutôt qu'elle n'ajoute, l'exécuter plus souvent que nécessaire est sans conséquence.

Pour résoudre les cibles sur une machine sans appeler l'API ni écrire sur le disque, exécutez d'abord ggshield honeytoken plant --list-targets.

Pour la capacité elle-même, y compris comment vérifier le placement et comment supprimer un honeytoken, voir Protéger les endpoints avec les Honeytokens.

Étape 6 - Déployer et vérifier

Commencez avec 10 à 20 machines surveillées, puis étendez par vagues (par exemple 1 % → 10 % → 25 % → 50 % → 100 %). Étalez les premiers scans sur des heures, pas des minutes.

Sur une machine témoin :

ggshield --version
sudo -i -u "$TARGET_USER" -- ggshield plugin list

Puis déclenchez le job d'inventaire MDM une fois. Allez dans Endpoint protection → Endpoints dans GitGuardian et confirmez que la machine apparaît avec un scan récent. Si vous avez déployé la protection par honeytoken, confirmez que la machine se signale également comme Protected. Voir Surveiller la couverture.

Surveillez seulement quelques signaux : succès de l'installation, plugin activé, heure du dernier scan, durée du scan, erreurs de téléversement et retours des utilisateurs sur les performances. Pour annuler, désactivez d'abord le scan d'inventaire planifié. Pour les honeytokens, désactivez le job de plantation et exécutez un passage ggshield honeytoken plant --remove-only pour effacer ce qui est déjà sur le disque.

Pour une checklist de pilote détaillée, voir Valider et déployer.