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

Utilisez cette page pour déployer Developer Endpoint Protection sur des endpoints gérés : scan de machine, protection par honeytoken, AI Hooks, et un inventaire des agents IA et serveurs MCP utilisés. Le même modèle fonctionne avec Jamf Pro, Iru (anciennement Kandji), Intune, Workspace ONE, Mosyle, Addigy, Canonical Landscape, ou avec des outils de gestion de configuration tels que Ansible, Puppet, Chef et Salt.

Nous recommandons de ne stocker aucun token GitGuardian sur l'endpoint. Injectez un token de compte de service admin à l'exécution, uniquement pour les tâches que votre MDM exécute : installer ggshield, installer le plugin de scan de machine, planter le honeytoken et lancer les scans.

Les hooks IA et git font exception. Ils se déclenchent dans la propre session du développeur, et non dans votre tâche MDM, donc cette machine a besoin d'une connexion développeur. Connectez le développeur et l'inventaire IA lui est également attribué.

Modèle de déploiement

Déployez chaque capacité comme sa propre tâche MDM afin de pouvoir l'auditer, la réparer ou la restaurer indépendamment. Les capacités sont facultatives et indépendantes les unes des autres, donc vous pouvez scanner une machine sans planter de honeytoken, ou installer les AI Hooks sans scanner. Nous recommandons néanmoins fortement de toutes les activer.

Tâche	Ce qu'elle fait	Token GitGuardian	Bonne adéquation MDM
Installer ou mettre à jour ggshield	Déployer le binaire CLI	Pas nécessaire	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	SAT admin, injecté à l'exécution	script d'audit/remédiation
Configuration de la machine	Exécuter ggshield machine setup pour configurer les AI Hooks, les hooks git et le honeytoken	SAT admin, injecté à l'exécution	script planifié, quotidien
Connexion développeur	ggshield auth logout --no-revoke, puis ggshield auth login en tant qu'utilisateur connecté	token personnel du développeur	script de remédiation, une fois par machine
Scan d'inventaire	Exécuter ggshield machine report	SAT admin, injecté à l'exécution, ou le token du développeur	script planifié, une fois par jour
Inventaire IA et MCP	Exécuter ggshield ai discover	token du développeur	script planifié

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

Ne conservez pas le SAT admin avec ggshield auth login --method token. Cela écrase la connexion du développeur, donc chaque commande ggshield ultérieure sur cette machine est rapportée comme le compte partagé, et un token admin reste sur le disque.

Étape 1 - Créer le token admin

Créez un token dédié de Service Account pour les tâches MDM. Ajoutez uniquement les scopes dont ces tâches ont besoin :

Scope	Pourquoi il est nécessaire
scan	Installer le plugin machine_scan par son nom, ce qui le télécharge depuis le catalogue GitGuardian
endpoints:send	Téléverser les résultats de scan, lorsque la tâche MDM exécute elle-même ggshield machine report
honeytokens:write	Planter des honeytokens sur la machine. Nécessaire uniquement pour la protection par honeytoken
honeytokens:check	Reconnaître vos propres honeytokens lors d'un scan et éviter de les signaler comme un secret ordinaire. Nécessaire uniquement pour les scans de machine

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

Étape 2 - Installer et gérer ggshield

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

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

Pour les déploiements macOS/Linux basés sur des scripts, installez d'abord uniquement le binaire, et définissez GGSHIELD_BIN_DIR sur un répertoire déjà présent dans le PATH de chacun :

curl -sSfL https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.sh | \
  GGSHIELD_BIN_DIR=/usr/local/bin bash -s -- --install-only

Auditez avec ggshield --version, qui doit indiquer la version 1.53.0 ou ultérieure pour les commandes de cette page.

Pour les grands parcs, préférez un cache de packages interne ou un package hébergé par MDM afin qu'aucune machine ne télécharge depuis internet en même temps.

Les exemples ci-dessous réutilisent cette recherche loggedInUser. Sous Linux, ou sur un serveur avec un utilisateur de scan dédié, utilisez plutôt cet utilisateur.

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

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

Le plugin de scan de machine doit être installé et activé avant d'exécuter ggshield machine report. Installez-le pour l'utilisateur qui exécutera le scan. Exécutez plutôt la tâche en tant que root et le plugin est installé à l'échelle de la machine afin que chaque utilisateur puisse le charger, ce qui est préférable lorsque plusieurs personnes partagent un hôte.

Si votre MDM peut préparer un package de plugin signé ou interne, installez ce package et la tâche n'a besoin d'aucun token :

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

Si vous installez par son nom, ggshield plugin install machine_scan contacte le catalogue de plugins GitGuardian. Passez le SAT admin dans GITGUARDIAN_API_KEY via stdin afin qu'il reste hors des lignes de commande et de l'historique du shell. Désactivez le traçage du shell (set -x) dans les scripts qui le manipulent.

astuce

Le token réside toujours dans l'environnement du processus, où ps -E sur macOS et /proc/<pid>/environ en tant que root sur Linux peuvent le lire. Configurez votre MDM pour masquer les variables d'environnement secrètes et le stdin capturé dans ses propres logs.

# Votre MDM injecte le SAT admin en tant que 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

Pour Linux, utilisez /bin/bash et votre utilisateur cible.

auth login et les commandes ggshield ultérieures utilisent par défaut US SaaS. Pour les instances EU ou self-hosted, passez GITGUARDIAN_INSTANCE dans le shell interne. L'URL de l'instance n'est pas un secret :

export GITGUARDIAN_INSTANCE=https://dashboard.eu1.gitguardian.com   # or your self-hosted instance URL

printf '%s\n' "$GGSHIELD_SAT" | sudo -i -u "$loggedInUser" -- \
  env GITGUARDIAN_INSTANCE="$GITGUARDIAN_INSTANCE" /bin/zsh -c \
  'IFS= read -r GITGUARDIAN_API_KEY && export GITGUARDIAN_API_KEY && exec ggshield plugin install machine_scan < /dev/null'

Utilisez ce même préfixe env GITGUARDIAN_INSTANCE=... sur chaque tâche admin ultérieure.

Auditez la réussite lorsque ggshield plugin list affiche machine_scan pour l'utilisateur de scan.

Étape 4 - Configurer les hooks et les honeytokens

ggshield machine setup configure les 3 protections d'endpoint en une seule exécution idempotente. Supprimez l'une d'elles avec --no-ai-hooks, --no-git-hooks ou --no-honeytokens. Exécutez-la en tant qu'utilisateur connecté, et injectez le SAT admin de la même manière qu'à l'Étape 3 :

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 setup < /dev/null'

Planifiez cette tâche quotidiennement. Elle ajoute les protections manquantes et laisse celles déjà en place :

• Écrit des hooks pour les agents IA qui ne sont pas encore protégés, et des hooks git lorsqu'ils ne sont pas encore imposés.
• Réconcilie la protection par honeytoken avec GitGuardian à chaque exécution : elle réécrit un honeytoken supprimé et retire celui que vous avez révoqué dans le dashboard. C'est pourquoi le plantage reste une tâche MDM avec honeytokens:write.

Pour choisir des assistants spécifiques, utilisez --agent. Pour en ignorer certains, utilisez --exclude-agent. Les deux acceptent claude-code, codex, copilot, cursor, vibe et vscode.

Honeytoken

Le plantage écrit un profil AWS leurre dans ~/.aws. L'utilisateur du processus décide de quel répertoire personnel il s'agit :

• En tant qu'utilisateur connecté : ce compte uniquement, ce qui suffit sur un ordinateur portable mono-utilisateur.
• En tant que root : chaque répertoire personnel d'utilisateur qu'il trouve (/Users, /home et similaires), afin que chaque compte sur un hôte partagé obtienne un leurre.

Sur un hôte partagé, exécutez la partie honeytoken en tant que root et injectez le SAT via stdin :

printf '%s\n' "$GGSHIELD_SAT" | sudo /bin/sh -c \
  'IFS= read -r GITGUARDIAN_API_KEY && export GITGUARDIAN_API_KEY && exec ggshield machine setup --no-ai-hooks --no-git-hooks < /dev/null'

Prévisualisez les cibles sans rien écrire : ggshield honeytoken plant --list-targets. Voir Protéger les endpoints avec les Honeytokens.

AI Hooks

Les hooks sont écrits dans la configuration de l'agent IA de l'utilisateur actuel (~/.claude, ~/.cursor et les autres outils pris en charge). machine setup configure chaque agent IA qu'il détecte pour ce compte.

Le hook s'exécute ensuite dans la session du développeur. Il lit le magasin d'identifiants de cet utilisateur, c'est pourquoi l'Étape 5 le connecte en tant que lui-même. S'il n'est pas connecté, le hook échoue en mode ouvert : il ne bloque pas, et l'outil affiche un avertissement indiquant que le contenu n'a pas été scanné.

Sur un hôte partagé, gardez les AI Hooks dans la tâche de l'utilisateur connecté et ignorez-les dans la tâche root (--no-ai-hooks). Voir Prévenir les fuites avec les AI Hooks.

Hooks git

Installe les hooks globaux pre-commit et pre-push. La portée suit l'utilisateur du processus :

• Root, ou --system : le core.hooksPath système de git, couvrant chaque utilisateur sur la machine.
• Non root, sans --system : le core.hooksPath global de git pour l'utilisateur actuel.

Un core.hooksPath qui pointe ailleurs (Husky, lefthook) a la priorité, et le hook ggshield ne s'y déclenche jamais. Une installation globale fait exception : lorsqu'un core.hooksPath global existe déjà, ggshield écrit son hook à l'intérieur de ce répertoire au lieu d'être masqué par lui.

ggshield machine doctor le rapporte par dépôt, et il résout le chemin effectif à partir du répertoire courant. Exécutez votre script d'audit MDM à l'intérieur d'un dépôt, sinon la vérification ne signifie rien.

Sur un hôte partagé, installez les hooks système en tant que root et ignorez les hooks git dans la tâche utilisateur, afin de ne pas définir un core.hooksPath global utilisateur qui masque le système pour ce compte. Les hooks git système n'ont pas besoin de token :

sudo ggshield machine setup --system --no-ai-hooks --no-honeytokens

Étape 5 - Connecter le développeur

Après les tâches admin, connectez le développeur afin que les AI Hooks, les hooks git et l'inventaire IA s'exécutent sous son appartenance. ggshield auth login demande automatiquement scan, honeytokens:check, endpoints:send et ai-discover:send.

auth login conserve un token existant si un est déjà stocké, donc déconnectez-vous d'abord. Utilisez --no-revoke pour que la déconnexion efface uniquement le token stocké.

sudo -i -u "$loggedInUser" -- ggshield auth logout --no-revoke
sudo -i -u "$loggedInUser" -- ggshield auth login

La commande de connexion ouvre un navigateur dans la session du développeur et provisionne un token personnel. Pour les instances EU ou self-hosted, passez --instance sur les deux commandes :

sudo -i -u "$loggedInUser" -- ggshield auth logout --no-revoke --instance https://dashboard.eu1.gitguardian.com
sudo -i -u "$loggedInUser" -- ggshield auth login --instance https://dashboard.eu1.gitguardian.com

US SaaS n'a pas besoin du drapeau --instance.

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

Planifiez une tâche MDM par jour qui exécute ggshield machine report --background. Elle scanne et envoie en une seule étape, voir Commandes. --background exécute le scan à faible priorité avec un budget CPU et mémoire réduit, afin qu'il entre moins en concurrence avec le travail du développeur.

remarque

--background nécessite le plugin machine_scan 0.65.0 ou ultérieur. Les versions antérieures rejettent le drapeau, donc mettez d'abord à jour le plugin avec l'Étape 3.

Injectez le SAT admin pour cette tâche, de la même manière qu'à l' Étape 3. Le scan ne dépend pas de la connexion du développeur, ce qui est plus simple à l'échelle d'un parc :

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 --background < /dev/null'

Cette tâche a besoin uniquement de endpoints:send. La détection s'exécute localement, et le plugin vérifie ce scope avant de téléverser. scan sert à télécharger le plugin depuis le catalogue, pas à scanner la machine.

Si vous voulez plutôt que chaque scan soit attribué au développeur, supprimez l'injection et exécutez-le en tant qu'utilisateur connecté après l' Étape 5, ce qui utilise son token :

sudo -i -u "$loggedInUser" -- ggshield machine report --background

Pour les instances EU ou self-hosted, passez l'instance via env, de la même manière qu'à l'Étape 3. La connexion ne la stocke pas pour les commandes ultérieures.

Si votre MDM ne peut pas exécuter de scripts planifiés de manière fiable, vous pouvez utiliser launchd ou un minuteur systemd comme solution de repli.

Étape 7 - Collecter l'inventaire IA et MCP

ggshield ai discover analyse les fichiers de configuration des assistants IA pris en charge et rapporte quels agents et serveurs MCP sont présents sur la machine. C'est sa propre tâche, distincte du scan de machine, donc planifiez-la séparément. Exécutez-la en tant qu'utilisateur connecté après l'Étape 5, afin qu'elle utilise son token et que l'inventaire lui soit attribué. L'outillage IA change moins souvent que les résultats de scan, donc un passage quotidien ou hebdomadaire suffit.

sudo -i -u "$loggedInUser" -- ggshield ai discover

Pour les instances EU ou self-hosted, passez l'instance via env, de la même manière qu'à l'Étape 3.

Pour savoir ce que collecte l'inventaire et comment les équipes de sécurité l'utilisent, voir Inventaire des agents IA et MCP.

Étape 8 - Déployer et vérifier

Commencez avec 10 à 20 machines surveillées, puis étendez par vagues. Sur une machine d'exemple, exécutez le contrôle de préparation en tant qu'utilisateur connecté, depuis l'intérieur d'un dépôt git afin que la vérification des hooks git résolve le core.hooksPath effectif :

sudo -i -u "$loggedInUser" -- /bin/zsh -c 'cd /path/to/a/repo && exec ggshield machine doctor'

machine doctor est en lecture seule et quitte avec un code non nul lorsqu'une vérification échoue, donc vous pouvez l'utiliser directement comme script d'audit MDM et conditionner la vague suivante à celui-ci. Chaque vérification échouée affiche sa propre correction. Après l'Étape 5, il devrait indiquer que le token du développeur atteint GitGuardian avec les scopes dont les protections ont besoin.

Déclenchez ensuite 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, et qu'elle est rapportée comme Protected si vous avez déployé la protection par honeytoken. Voir Surveiller la couverture.

Pour effectuer une restauration, désactivez d'abord les tâches planifiées, en particulier machine setup. Puis effacez ce qui est déjà sur le disque. ggshield auth logout en tant qu'utilisateur connecté supprime son token personnel. Révoquez le SAT admin dans votre workspace pour couvrir l'ensemble du parc en une seule fois.

Pour la checklist du pilote, les tailles de vagues et ce qu'il faut surveiller à chaque étape, voir Valider et déployer.