Déployer ggshield à grande échelle avec un token de compte de service
Utilisez cette page pour déployer Machine Scan sur les endpoints gérés et téléverser les inventaires de scan vers GitGuardian selon une planification. Le même schéma fonctionne avec Jamf Pro, Kandji, Intune, Workspace ONE, Mosyle, Addigy, Canonical Landscape, ou avec des outils de gestion de configuration tels que Ansible, Puppet, Chef et Salt.
Modèle de déploiement
Conservez le déploiement sous forme de trois jobs MDM distincts. Cela rend chaque partie facile à auditer, réparer et annuler.
| Job | Ce qu'il fait | Token GitGuardian | Bon usage MDM |
|---|---|---|---|
Installer ou mettre à jour ggshield | Déployer le binaire CLI | Non requis | script de déploiement de package ou de remédiation |
Installer ou mettre à jour machine_scan | Ajouter le plugin Machine Scan pour l'utilisateur qui exécute le scan | Uniquement pour installer par nom | script d'audit/remédiation |
| Scan d'inventaire | Exécuter ggshield machine inventory | Requis | script planifié, une fois par jour |
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 l'installez par nom) et le téléversement
quotidien de l'inventaire.
| 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 machines dans votre workspace |
Utilisez un token de Service Account dédié (pas un token personnel) et n'exécutez pas
ggshield auth login sur les machines du parc. Si vous préparez un package de plugin
signé ou interne au lieu de l'installer par nom, le job d'installation n'a besoin
d'aucun token.
Stockez le token dans le coffre à secrets de votre MDM ou dans un gestionnaire de secrets, et injectez-le uniquement au moment de l'exécution.
endpoints:send est le seul scope qui écrit dans votre workspace, c'est donc
celui qu'il faut confiner. Le téléversement quotidien est exécuté par un unique job
planifié, 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 scan, honeytokens:check, endpoints:send au job de
téléversement : un token d'installation compromis ne pourra alors ni pousser un
inventaire falsifié ni masquer des résultats dans votre dashboard. Le coût est un
secret supplémentaire à faire tourner. Si vous installez le plugin depuis un package
préparé plutôt que par nom, le job d'installation n'a besoin d'aucun token, et un
seul token de téléversement 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 parc 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 le programme d'installation Windows ou exécutez le programme d'installation 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/.rpmou exécutez le programme d'installation 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 grands parcs, préférez un cache de packages interne ou un package hébergé par le MDM afin que toutes les machines ne téléchargent pas depuis Internet en même temps.
Étape 3 - Installer Machine Scan pour l'utilisateur du scan
Machine scanning doit être installé et activé avant d'exécuter
ggshield machine inventory. Le plugin est à portée 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 ultérieur et contacte le catalogue de plugins GitGuardian.
Injectez le token de compte de service au moment de l'exécution ; ne le stockez pas
avec ggshield auth login sur l'endpoint. Pour les instances EU 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 la réussite lorsque ggshield plugin list affiche machine_scan pour
l'utilisateur du scan.
Étape 4 - Exécuter le scan d'inventaire quotidien
Planifiez un job MDM par jour qui injecte le token de compte de service au moment
de l'exécution et lance ggshield machine inventory en tant qu'utilisateur du scan.
# 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 inventory < /dev/null'
Pour Linux, utilisez /bin/bash et votre utilisateur cible. Pour les instances EU
ou Self-Hosted, exportez également GITGUARDIAN_INSTANCE dans le même shell.
Ce schéma tient le token à l'écart des arguments de ligne de commande, des fichiers,
des logs et de ggshield auth login. Cela compte parce que les logiciels malveillants
de supply-chain récupèrent couramment des identifiants sur les postes de travail
dans les fichiers, les environnements shell et les configurations de gestionnaires
de packages. Désactivez le traçage shell (set -x) dans les scripts qui manipulent
le token.
Si votre MDM ne peut pas exécuter des scripts planifiés de manière fiable, vous
pouvez utiliser launchd ou un timer systemd comme solution de repli. Conservez
le token dans un fichier accessible uniquement à root et supprimez-le lors de la
désinstallation.
Étape 5 - Déployer et vérifier
Commencez avec 10 à 20 machines surveillées, puis étendez par vagues (par exemple 1 % → 10 % → 25 % → 50 % → 100 %). Répartissez les premiers scans sur des heures, pas des minutes.
Sur une machine témoin :
ggshield --version
sudo -i -u "$TARGET_USER" -- ggshield plugin list
Déclenchez ensuite 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.
Surveillez seulement quelques signaux : succès de l'installation, plugin activé, date 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 une checklist de pilote détaillée, consultez Valider et déployer.
