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

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

Nous vous recommandons de ne stocker aucun token GitGuardian sur l'endpoint. Injectez un token de compte de service admin au moment de l'exécution, uniquement pour les jobs exécutés par votre MDM : installer ggshield, installer le plugin de scan des machines, planter le honeytoken et exécuter les scans.

Les hooks IA et git font exception. Ils se déclenchent dans la session propre du développeur, et non dans votre job MDM, de sorte que cette machine a besoin d'une connexion développeur. Connectez le développeur et l'inventaire IA lui sera également attribué.

Modèle de déploiement

Déployez chaque capacité comme son propre job 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, vous pouvez donc scanner une machine sans planter de honeytoken, ou installer les AI Hooks sans scanner. Nous vous recommandons néanmoins vivement de toutes les activer.

Job	Ce qu'il fait	Token GitGuardian	Bonne adéquation MDM
Installer ou mettre à jour ggshield	Déployer le binaire de la CLI	Non 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é au moment de 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é au moment de l'exécution	script planifié, quotidien
Connexion du 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é au moment de l'exécution, ou 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 persistez pas le SAT admin avec ggshield auth login --method token. Cela écrase la connexion du développeur, de sorte que chaque commande ggshield ultérieure sur cette machine se rapporte au compte partagé, et un token admin reste sur le disque.

Étape 1 - Créer le token admin

Créez un token de compte de service dédié pour les jobs MDM. Ajoutez uniquement les scopes dont ces jobs 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	Envoyer les résultats de scan, lorsque le job MDM exécute lui-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 le signaler comme un secret ordinaire. Nécessaire uniquement pour les scans de machines

Stockez le token dans votre magasin de secrets MDM ou votre gestionnaire de secrets et injectez-le au moment de 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 géré ou une affectation 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 tout le monde :

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 rapporter 1.53.0 ou une version 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 le MDM afin que chaque machine ne télécharge pas 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 cet utilisateur à la place.

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

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

Le plugin machine scan 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 le job en tant que root et le plugin est installé à l'échelle de la machine afin que chaque utilisateur puisse le charger, ce qui convient mieux lorsque plusieurs personnes partagent un hôte.

Si votre MDM peut préparer un package de plugin signé ou interne, installez ce package et le job 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. Transmettez 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 vit toujours dans l'environnement du processus, où ps -E sous macOS et /proc/<pid>/environ en tant que root sous Linux peuvent le lire. Configurez votre MDM pour censurer les variables d'environnement secrètes et le stdin capturé de 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 le SaaS US. Pour les instances EU ou Self-Hosted, transmettez GITGUARDIAN_INSTANCE au 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 job admin ultérieur.

Auditez le succès 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-en une 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 ce job quotidiennement. Il ajoute les protections manquantes et laisse celles déjà en place :

• Écrit les hooks pour les agents IA qui ne sont pas encore protégés, et les hooks git lorsqu'ils ne sont pas encore imposés.
• Réconcilie la protection par honeytoken avec GitGuardian à chaque exécution : il réécrit un honeytoken supprimé et retire celui que vous avez révoqué dans le dashboard. C'est pourquoi la plantation reste un job 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

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

• En tant qu'utilisateur connecté : ce compte uniquement, ce qui suffit sur un ordinateur portable à une seule personne.
• En tant que root : chaque home d'utilisateur qu'il trouve (/Users, /home et similaires), de sorte que chaque compte sur un hôte partagé reçoit 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. Consultez 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é, conservez les AI Hooks dans le job de l'utilisateur connecté et ignorez-les dans le job root (--no-ai-hooks). Consultez 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.
• Pas root, pas de --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 se déclenche jamais là-bas. Une installation globale est l'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 celui-ci.

ggshield machine doctor le rapporte par dépôt, et il résout le chemin effectif à partir du répertoire actuel. 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 le job 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 jobs 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 l'un est déjà stocké, alors déconnectez-vous d'abord. Utilisez --no-revoke afin que la déconnexion ne fasse qu'effacer le token stocké.

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

La commande login ouvre un navigateur dans la session du développeur et provisionne un token personnel. Pour les instances EU ou Self-Hosted, transmettez --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

Le SaaS US n'a pas besoin de l'option --instance.

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

Planifiez un job MDM par jour qui exécute ggshield machine report. Il scanne et envoie en une seule étape, consultez Commandes.

Injectez le SAT admin pour ce job, 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 < /dev/null'

Ce job n'a besoin que de endpoints:send. La détection s'exécute localement, et le plugin vérifie ce scope avant d'envoyer. scan sert à télécharger le plugin depuis le catalogue, pas à scanner la machine.

Si vous souhaitez 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

Pour les instances EU ou Self-Hosted, transmettez 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 des scripts planifiés de manière fiable, vous pouvez utiliser launchd ou un timer systemd en 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. Il s'agit de son propre job, distinct du scan des machines, alors planifiez-le séparément. Exécutez-le en tant qu'utilisateur connecté après l'Étape 5, afin qu'il utilise son token et que l'inventaire lui soit attribué. Les outils IA changent 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, transmettez l'instance via env, de la même manière qu'à l'Étape 3.

Pour savoir ce que l'inventaire collecte et comment les équipes de sécurité l'utilisent, consultez 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'échantillon, exécutez la vérification 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 se termine avec un code non nul lorsqu'une vérification échoue, de sorte que vous pouvez l'utiliser directement comme script d'audit MDM et conditionner la vague suivante à celui-ci. Chaque vérification échouée imprime son propre correctif. Après l'Étape 5, il devrait rapporter que le token du développeur atteint GitGuardian avec les scopes dont les protections ont besoin.

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

Pour effectuer un rollback, désactivez d'abord les jobs planifiés, 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 tout le parc en une seule fois.

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