Déployer ggshield à grande échelle avec un token de compte de service
Qu'est-ce qu'un token de compte de service ?
Un compte de service est un type spécial de clé d'API destiné à représenter un utilisateur non humain qui doit s'authentifier et être autorisé pour des scénarios tels que le scan de secrets dans les pipelines CI ou le traitement par lots des incidents ouverts.
Prérequis
Pour créer un token de compte de service, suivez les instructions dans la documentation des comptes de service.
Vue d'ensemble de bout en bout
À un haut niveau, un déploiement à l'échelle d'un parc se résume à cinq étapes :
- Créez un token de compte de service GitGuardian (SAT) dédié avec le scope
endpoints:send. - Déployez
ggshieldsur les endpoints via votre MDM ou outil de gestion de configuration, en le maintenant continuellement appliqué et à jour. - Installez et activez le plugin
machine_scan— traitez-le comme un élément de conformité à part entière. - Stockez le SAT dans un coffre-fort de secrets sécurisé (variable secrète du MDM ou gestionnaire de secrets dédié). Ne l'intégrez jamais dans des scripts, fichiers de configuration ou arguments de la CLI.
- Configurez une tâche planifiée quotidienne qui injecte le SAT à l'exécution en tant que
GITGUARDIAN_API_KEY(etGITGUARDIAN_INSTANCEsi nécessaire) et exécuteggshield machine inventory.
Étape 1 - Créer le token de compte de service
Créez un SAT dédié depuis un compte GitGuardian Account Admin.
Scopes requis :
endpoints:send
honeytokens:check
Ces scopes sont nécessaires pour que les endpoints puissent envoyer des données d'inventaire machine à GitGuardian sans déclencher de HoneyTokens depuis votre compte.
- Utilisez un SAT dédié pour la protection des secrets sur les endpoints.
- N'utilisez pas de Personal Access Tokens.
- N'exécutez pas
ggshield auth loginsur les endpoints. - Ne codez pas en dur le SAT dans des scripts publics, packages ou documentation.
Étape 2 - Installer et gérer ggshield avec un MDM
À grande échelle, ne traitez pas l'installation comme un script ponctuel. Traitez ggshield comme un composant géré par MDM qui est vérifié en permanence.
Flux MDM recommandé
| Action MDM | Ce qu'elle doit faire |
|---|---|
| Audit/vérification | Vérifiez que ggshield est installé, que le binaire est de confiance selon votre politique et que la version est la version approuvée/actuelle. |
| Installation | Téléchargez, vérifiez et installez la version approuvée, puis vérifiez à nouveau le binaire. |
| Mise à jour | Lorsque l'audit détecte une version obsolète, la remédiation installe la version approuvée plus récente. |
Chemins typiques des binaires
| Plateforme | Chemin typique |
|---|---|
| macOS | /usr/local/bin/ggshield |
| Linux | /usr/bin/ggshield |
Validez l'installation avec :
ggshield --version
Notes d'implémentation
- Sur macOS, validez la signature du package et du binaire installé selon votre politique.
- Sur Linux, validez les checksums/signatures des packages selon votre politique.
- Pour les grands parcs, utilisez un cache de package interne ou un package hébergé par le MDM au lieu que chaque endpoint télécharge indépendamment.
- Vous pouvez suivre soit la dernière version disponible, soit une version épinglée approuvée en interne.
Étape 3 - Installer, gérer et mettre à jour le plugin machine scan avec un MDM
Le scan machine doit être installé et activé avant d'exécuter ggshield machine inventory.
À grande échelle, gérez le plugin machine scan comme son propre élément de conformité MDM. Cela vous permet d'installer, vérifier, mettre à jour et corriger les dérives indépendamment du scan d'inventaire quotidien.
Modèle d'audit MDM
| Action MDM | Ce qu'elle doit vérifier ou faire |
|---|---|
| Audit/vérification | Confirmez que ggshield existe. Confirmez que machine_scan est activé pour le contexte utilisateur qui exécutera le scan. Confirmez éventuellement que la version du plugin est la version approuvée/actuelle. |
| Installation | Obtenez le package de plugin approuvé pour l'architecture du endpoint, vérifiez-le, installez-le, activez machine_scan, puis vérifiez avec ggshield plugin list. |
| Mise à jour | Si le plugin est manquant ou obsolète, relancez l'installation. |
| Réparation du contexte utilisateur | Comme la configuration du plugin est au niveau utilisateur, installez/activez-le pour l'utilisateur actif ou cible du scan, et pas uniquement pour root/admin. |
Commandes génériques utilisées par le MDM :
export GITGUARDIAN_API_KEY="<SAT_FROM_SECRET_STORE>"
export GITGUARDIAN_INSTANCE="<GITGUARDIAN_INSTANCE_URL>"
ggshield plugin install machine_scan
ggshield plugin enable machine_scan
ggshield plugin list
Installation au niveau utilisateur
La configuration du plugin est au niveau utilisateur. La tâche MDM s'exécute normalement en tant que root/admin, mais le scan d'inventaire est souvent exécuté en tant qu'utilisateur connecté. La remédiation doit donc installer et activer le scan machine dans le même contexte utilisateur que celui utilisé pour le scan.
Modèle macOS :
export GITGUARDIAN_API_KEY="<SAT_FROM_SECRET_STORE>"
export GITGUARDIAN_INSTANCE="<GITGUARDIAN_INSTANCE_URL>"
GGSHIELD_BIN="/usr/local/bin/ggshield"
loggedInUser=$(scutil <<< "show State:/Users/ConsoleUser" | awk '/Name :/ && !/loginwindow/ {print $3}')
# Management/root context.
"$GGSHIELD_BIN" plugin install machine_scan
"$GGSHIELD_BIN" plugin enable machine_scan
# Scan user context.
if [ -n "$loggedInUser" ] && [ "$loggedInUser" != "root" ]; then
sudo -i -u "$loggedInUser" -- "$GGSHIELD_BIN" plugin install machine_scan
sudo -i -u "$loggedInUser" -- "$GGSHIELD_BIN" plugin enable machine_scan
sudo -i -u "$loggedInUser" -- "$GGSHIELD_BIN" plugin list
fi
Modèle Linux :
export GITGUARDIAN_API_KEY="<SAT_FROM_SECRET_STORE>"
export GITGUARDIAN_INSTANCE="<GITGUARDIAN_INSTANCE_URL>"
GGSHIELD_BIN="/usr/bin/ggshield"
TARGET_USER="<target-user>"
"$GGSHIELD_BIN" plugin install machine_scan
"$GGSHIELD_BIN" plugin enable machine_scan
sudo -i -u "$TARGET_USER" -- "$GGSHIELD_BIN" plugin install machine_scan
sudo -i -u "$TARGET_USER" -- "$GGSHIELD_BIN" plugin enable machine_scan
sudo -i -u "$TARGET_USER" -- "$GGSHIELD_BIN" plugin list
Notes d'implémentation
- Si le package du plugin est copié vers un chemin temporaire, assurez-vous que l'utilisateur cible peut le lire.
- Si aucun utilisateur n'est connecté, installez/activez pour le contexte de gestion et laissez l'exécution MDM suivante réparer le contexte utilisateur lorsqu'un utilisateur est disponible.
- Gardez la tâche d'installation du plugin séparée de la tâche de scan d'inventaire lorsque c'est possible.
- Pour les mises à jour, laissez l'audit MDM échouer lorsque le plugin est manquant ou obsolète, puis remédiez en installant à nouveau le package approuvé.
Étape 4 - Exécuter le scan d'inventaire en toute sécurité
Au moment du scan, ggshield a besoin du SAT en tant que GITGUARDIAN_API_KEY.
Forme simple :
export GITGUARDIAN_API_KEY="<SAT_FROM_SECRET_STORE>"
export GITGUARDIAN_INSTANCE="<GITGUARDIAN_INSTANCE_URL>"
ggshield machine inventory
Pour les endpoints gérés, évitez d'exposer le SAT dans les arguments de ligne de commande, les logs ou les fichiers.
Désactivez le traçage du shell (set -x) dans tout script qui manipule le SAT.
Étape 5 - Configurer les tâches MDM et la tâche planifiée
Utilisez le MDM pour gérer trois préoccupations distinctes :
| Tâche MDM | Objectif | Nécessite le SAT ? | Récurrence suggérée |
|---|---|---|---|
Installation/application de ggshield | Installer, vérifier et mettre à jour le binaire ggshield. | Non | Planning de conformité/application du MDM. |
| Installation/application du plugin machine scan | Installer, vérifier, activer et mettre à jour machine_scan pour l'utilisateur du scan. | Oui | Planning de conformité/application du MDM. |
| Scan d'inventaire | Exécuter ggshield machine inventory. | Oui | Une fois par jour. |
Paramètres de la tâche de scan d'inventaire
| Paramètre | Recommandation |
|---|---|
| Objectif du script | Exécuter ggshield machine inventory |
| Fréquence | Une fois par jour |
| Exécuter en tant que | Root/admin pour le script de gestion |
| Utilisateur du scan | Utilisateur actif pour les postes de travail, sauf si un autre contexte est requis |
| Entrée du secret | SAT injecté en tant que variable secrète, par exemple GGSHIELD_SAT |
| Premier déploiement | 10 à 20 machines surveillées |
| Grands parcs | Répartissez les appareils en groupes/plannings afin que les scans ne démarrent pas tous en même temps |
| Critères de réussite | La commande se termine avec succès et la machine apparaît dans le dashboard Endpoints de GitGuardian avec un dernier scan à jour |
| Logs | Succès/échec, identifiant de l'endpoint, date et durée du scan si disponibles |
Pourquoi des tâches séparées
- La conformité MDM peut réparer automatiquement les composants manquants/obsolètes.
- La mise à jour du binaire ou du plugin ne nécessite pas de modifier le planning du scan.
Plannings locaux facultatifs
Si la planification MDM n'est pas disponible ou suffisante, des planificateurs locaux peuvent être utilisés. Validez cette approche dans votre environnement avant un déploiement à grande échelle.
| Plateforme | Planificateur local | Conseils |
|---|---|---|
| macOS | LaunchDaemon launchd | Exécutez un script de scan local quotidiennement. Ne mettez pas le SAT dans le plist. |
| Linux | Timer systemd | Exécutez un script de scan local quotidiennement. Utilisez un stockage local protégé pour les identifiants uniquement si l'injection de secrets par le MDM n'est pas disponible. |
| Solution de repli historique | cron | À utiliser uniquement lorsque le MDM ou les planificateurs natifs ne sont pas disponibles. |
Recommandation de récurrence
Valeur par défaut recommandée : une fois par jour par endpoint.
- Cela offre à GitGuardian une fraîcheur suffisante de l'inventaire des endpoints.
- Cela devrait être presque transparent pour la plupart des utilisateurs après le premier scan, grâce à la mise en cache.
- Des scans moins fréquents peuvent ne pas envoyer suffisamment de données et réduire la visibilité sur l'exposition des secrets.
- Des scans plus fréquents sont possibles pour des cas d'usage spécifiques, mais plus d'une fois par jour n'est pas recommandé comme politique par défaut pour des raisons de performance et de charge du parc/de l'API.
Runbook de déploiement
Utilisez cette checklist pour suivre votre déploiement depuis la configuration initiale jusqu'à la couverture complète du parc.
| Phase | Action | Termin é quand |
|---|---|---|
| 1. Créer l'accès | Créez un token de compte de service (SAT) GitGuardian dédié. | Le SAT existe avec les scopes endpoints:send et honeytokens:check. |
| 2. Installer ggshield | Déployez le package ggshield via MDM, RMM ou outil de gestion de configuration. | Le endpoint peut exécuter ggshield --version. |
| 3. Activer le scan machine | Installez et activez le plugin machine scan. | ggshield plugin list affiche machine_scan pour l'utilisateur du scan. |
| 4. Configurer l'authentification | Stockez le SAT dans le coffre-fort de secrets du MDM/RMM ou un autre mécanisme de secret contrôlé. | La tâche de scan reçoit le SAT en tant que GITGUARDIAN_API_KEY à l'exécution. |
| 5. Planifier les scans | Configurez une tâche planifiée quotidienne. | ggshield machine inventory s'exécute sans interaction utilisateur. |
| 6. Valider le premier groupe | Déployez sur 10 à 20 machines surveillées. | Les machines apparaissent dans le dashboard Endpoints de GitGuardian avec des performances de scan acceptables ; voir Valider et déployer. |
| 7. Étendre le déploiement | Étendez par vagues en pourcentage. | Les taux de succès/erreur restent acceptables à chaque vague. |
Après le déploiement
Lorsque les scans planifiés réussissent, les résultats sont disponibles dans le menu Endpoints Protection de votre dashboard GitGuardian :
- Machines — KPI du parc et tableau filtrable des endpoints avec l'heure du dernier scan et le résumé de sévérité
- Endpoint detail — secrets découverts par machine, historique des scans et inventaire facultatif des agents IA
Utilisez Valider et déployer pour la checklist du dashboard avant d'étendre au-delà de votre groupe pilote. Pour ce que chaque vue affiche, voir Concepts fondamentaux.
