Déployer ggshield à grande échelle avec un jeton de compte de service

Utilisez cette page pour déployer Machine Scan sur des endpoints gérés et charger 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 avec des outils de gestion de configuration tels que Ansible, Puppet, Chef et Salt.

Modèle de déploiement

Gardez le déploiement en trois tâches MDM distinctes. Cela rend chaque partie facile à auditer, réparer et annuler.

Tâche	Rôle	Jeton 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 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

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 jeton

Créez un jeton dédié de Service Account avec les scopes scan, honeytokens:check et endpoints:send. Un seul jeton couvre à la fois l'installation du plugin (lorsque vous installez par nom) et le chargement 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	Charger l'inventaire de la machine dans votre workspace

Utilisez un jeton de Service Account dédié (pas un jeton 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 d'installer par nom, la tâche d'installation n'a besoin d'aucun jeton.

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

Renforcement facultatif : diviser en deux jetons

endpoints:send est le seul scope qui écrit dans votre workspace, c'est donc celui à contenir. Le chargement quotidien s'exécute comme une tâche planifiée unique, mais la tâche d'installation/mise à jour s'exécute sur chaque machine et est bien plus exposée. Donnez à la tâche d'installation/mise à jour un jeton avec seulement scan, et réservez scan, honeytokens:check, endpoints:send à la tâche de chargement : un jeton d'installation compromis ne peut alors pas pousser d'inventaire falsifié ni masquer des détections 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, la tâche d'installation n'a besoin d'aucun jeton, donc un unique jeton de chargement est déjà à privilège minimal.

É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 géré ou une affectation de script.
• Landscape / Ansible / Puppet / Chef / Salt : installez le .deb/.rpm ou exécutez le programme d'installation officiel, puis appliquez 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 package interne ou un package hébergé sur 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 de scan

Machine scanning doit être installé et activé avant d'exécuter ggshield machine report. Le plugin est propre à l'utilisateur, alors installez-le 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 jeton GitGuardian n'est requis pour la tâche 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 requiert ggshield 1.51.0 ou ultérieur et contacte le catalogue de plugins GitGuardian. Injectez le jeton 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 scripts de style 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 une tâche MDM par jour qui injecte le jeton de compte de service 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 EU ou Self-Hosted, exportez également GITGUARDIAN_INSTANCE dans le même shell.

Ce modèle maintient le jeton hors des arguments de ligne de commande, des fichiers, des logs et de ggshield auth login. C'est important car les malwares de type supply-chain scrutent couramment les postes de travail à la recherche d'identifiants 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 jeton.

Si votre MDM ne peut pas exécuter des scripts planifiés de manière fiable, vous pouvez utiliser launchd ou un timer systemd en solution de repli. Conservez le jeton dans un fichier accessible uniquement au 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

Puis déclenchez la tâche 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é, heure du dernier scan, durée du scan, erreurs de chargement et retours de performance des utilisateurs. Pour revenir en arrière, désactivez d'abord le scan d'inventaire planifié.

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