Aller au contenu principal

Qu'est-ce que ggscout ?

GitGuardian Scout (ggscout) est une application en ligne de commande qui collecte les secrets et leurs métadonnées depuis vos gestionnaires de secrets et synchronise ces données avec votre plateforme GitGuardian.

Pourquoi collecter les secrets ?​

Lorsqu'un secret fuit dans votre dépôt de code ou est exposé dans votre infrastructure, une question cruciale se pose : ce secret est-il actuellement utilisé, et où ? Sans un inventaire de vos secrets de production, répondre à cette question est chronophage et source d'erreurs.

ggscout résout ce problème en :

  1. Créant un inventaire des secrets stockés dans vos gestionnaires de secrets (HashiCorp Vault, AWS Secrets Manager, etc.)
  2. Classifiant chaque valeur avec le Secrets Detection Engine avant le hachage
  3. Vérifiant chaque secret auprès de son fournisseur pour savoir s'il est toujours valide, quelles permissions il accorde, qui en est le propriétaire et quand il expire. Voir Vérifier la validité et les permissions à la source
  4. Hachant ces secrets localement à l'aide de l'algorithme HMSL : les secrets ne quittent jamais votre infrastructure en clair
  5. Réconciliant cet inventaire avec les secrets détectés par GitGuardian dans votre base de code ou d'autres sources

Cette réconciliation permet trois fonctionnalités clés :

1. Étendre la couverture de détection​

En maintenant un inventaire des secrets stockés dans votre vault, vous pouvez détecter lorsque ces secrets sont compromis ailleurs dans votre périmètre. Lorsque GitGuardian détecte un secret ayant fuité, il peut immédiatement vous indiquer s'il correspond à un secret actuellement stocké dans votre vault.

Exemple : un développeur commite accidentellement une clé API dans un dépôt public. Avec ggscout, vous savez instantanément que cette clé provient de votre HashiCorp Vault de production et quelle application l'utilise.

2. Améliorer la priorisation des incidents​

Les secrets stockés dans un vault s'accompagnent de métadonnées précieuses : chemins du vault, durées de bail, politiques de rotation, applications associées et environnements. Ce contexte vous aide à prioriser les incidents à remédier en premier.

Exemple : deux secrets fuient. L'un a un bail de 90 jours et n'est utilisé que dans un environnement de développement. L'autre a un bail de 365 jours et est utilisé par un service de paiement en production. Les métadonnées de ggscout vous aident à prioriser d'abord le secret de production.

3. Amorcer la remédiation des incidents​

En identifiant les secrets qui ne sont pas dans votre vault (secrets non stockés), ggscout peut vous aider à les sécuriser. Il peut automatiquement pousser les secrets non stockés dans votre gestionnaire de secrets, fournissant à vos développeurs le chemin du vault pour mettre à jour leur code.

Exemple : GitGuardian détecte un mot de passe de base de données en dur dans un ancien dépôt. À l'aide de ggscout, vous pouvez pousser ce secret dans votre vault et fournir aux développeurs le chemin exact pour le référencer, simplifiant ainsi le processus de remédiation.

Aucun secret ne sort de votre environnement !

Les valeurs des secrets ne quitteront jamais votre environnement en clair !

Les valeurs des secrets sont hachées à l'aide de l'algorithme de hachage HMSL avant d'être envoyées à votre workspace GitGuardian. D'autres métadonnées non sensibles comme les noms des secrets, les chemins dans le vault, la date de création, la durée de bail, etc. sont également collectées pour vous aider dans le processus de remédiation.

Collecter les secrets en toute sécurité pour faciliter la remédiation des incidents​

Une fois que vous avez déployé et configuré ggscout dans votre environnement, il s'exécute comme suit :

  1. Il collecte les secrets et les métadonnées associées depuis les gestionnaires de secrets que vous avez configurés.
  2. Il classifie chaque valeur avec le Secrets Detection Engine.
  3. Il vérifie chaque secret classifié auprès de son fournisseur : validité, permissions, propriétaire et expiration.
  4. Il hache les secrets à l'aide de l'algorithme de hachage HMSL.
  5. Il envoie les données collectées à GitGuardian et les réconcilie avec les incidents de secrets existants.

Scout Flow

C'est tout, vous pouvez commencer à exploiter ces fonctionnalités depuis votre plateforme GitGuardian !

Classifier les secrets avec le Secrets Detection Engine​

Avant le hachage, ggscout fait passer chaque valeur collectée par le même Secrets Detection Engine que celui utilisé pour le scan de code : plus de 600 détecteurs spécifiques et génériques.

La classification repose sur la valeur, et pas seulement sur le nom de la clé. Un secret stocké sous un nom générique tel que CONFIG_3 est reconnu si la valeur correspond à un détecteur. Une clé nommée MY_TOKEN dont la valeur est disabled n'est pas traitée comme un identifiant.

Lorsqu'un détecteur correspond, ggscout associe ce détecteur au secret. GitGuardian en déduit ensuite le type de détecteur (générique ou spécifique), la famille de secrets, la catégorie et le fournisseur, et les fait apparaître dans l'inventaire NHI. Les valeurs qui ne correspondent à aucun détecteur sont tout de même inventoriées et étiquetées Unknown. Rien n'est supprimé.

ggscout gère également les valeurs qui contiennent plus d'un secret :

  • Un fichier en texte brut tel qu'un .env est découpé en une entrée d'inventaire par secret détecté, chacune avec son propre hachage, afin qu'elle puisse être corrélée aux fuites de ces tokens.
  • Les champs apparentés qui forment un seul identifiant (par exemple un nom d'utilisateur et un mot de passe dans le même objet du vault) sont classifiés ensemble.
Nécessite ggscout 0.32.0 ou une version ultérieure

Vous devez exécuter ggscout 0.32.0 ou une version ultérieure pour que la classification apparaisse dans NHI Governance. Épinglez les images Docker et les charts Helm à cette version ou à latest après sa publication. La classification est toujours activée : il n'y a rien à activer dans ggscout.toml.

Vérifier la validité et les permissions à la source​

Une fois qu'une valeur est classifiée, ggscout pose quatre questions au fournisseur du secret, depuis l'intérieur de votre réseau, avant de hacher la valeur :

  • Est-il toujours valide ? Cet identifiant peut-il encore s'authentifier, ou a-t-il été révoqué ?
  • Que peut-il faire ? Les portées ou permissions que le fournisseur signale, telles que repo et admin:org pour un token GitHub.
  • Qui en est le propriétaire ? Le compte côté fournisseur derrière l'identifiant, avec son statut d'administrateur lorsque le fournisseur l'expose.
  • Quand expire-t-il ? La date d'expiration, lorsque le fournisseur en définit une.

Les réponses accompagnent le secret haché jusqu'à GitGuardian et apparaissent dans l'inventaire NHI sous forme de colonne et de filtre Validity, et sous forme de permissions, propriétaire et expiration dans le détail de l'identité. Lorsque le même secret figure également dans un incident de secret, GitGuardian fusionne les deux verdicts et conserve le plus récent.

ggscout utilise les mêmes vérificateurs de validité et analyseurs de secrets que la plateforme GitGuardian. Chaque vérification s'exécute avec une nouvelle récupération, de sorte qu'un verdict n'est jamais plus ancien que votre planning d'exécution.

Pourquoi vérifier depuis ggscout plutôt que depuis GitGuardian​

GitGuardian vérifie déjà la validité des secrets ayant fuité depuis ses propres serveurs. Exécuter la vérification dans ggscout vous donne des réponses plus fiables pour les secrets stockés dans un vault :

  • Portée : ggscout s'exécute à côté du secret. Il peut atteindre un GitLab Self-Hosted, un Vault interne, une base de données derrière un VPN, ou tout fournisseur qui n'accepte que le trafic provenant de votre réseau. Depuis les serveurs de GitGuardian, ces vérifications reviennent avec Failed to check.
  • Pas de liste d'autorisation : vous n'avez pas besoin d'ouvrir vos fournisseurs aux adresses IP de GitGuardian.
  • Couverture : la vérification s'exécute sur chaque secret que ggscout collecte, et pas seulement sur ceux qui apparaissent aussi dans un incident. Vous obtenez la liste des identifiants révoqués qui traînent encore dans vos vaults, et ceux qui sont surprivilégiés, sans attendre une fuite.
  • Fraîcheur : les verdicts sont actualisés à chaque exécution, selon le planning que vous contrôlez.

Ce qui est envoyé à GitGuardian​

Uniquement le résultat : un statut de validité, la liste triée des portées, l'identité du propriétaire signalée par le fournisseur (ID utilisateur, e-mail, indicateur d'administrateur), la date d'expiration et l'heure de la vérification. Lorsqu'une vérification échoue, ggscout envoie une catégorie d'erreur (timeout, network, rate_limited, revoked, ...) et jamais le texte d'erreur propre au fournisseur. La valeur du secret elle-même reste dans votre réseau et est hachée comme d'habitude.

Le statut de validité est l'un des suivants :

StatutSignification
validLe fournisseur a accepté l'identifiant.
invalidLe fournisseur l'a rejeté : révoqué, expiré ou incorrect.
failed_to_checkUne vérification s'est exécutée mais n'a pas pu trancher : timeout, erreur réseau, limite de débit ou accès refusé.
not_checkedUn vérificateur existe pour ce détecteur mais ne s'est pas exécuté, par exemple parce que l'étape est désactivée.
no_checkerAucun détecteur n'a correspondu, ou le détecteur n'a pas de vérificateur.

Ce que la vérification fait sur le fournisseur​

La plupart des vérifications sont des appels en lecture seule via HTTPS sortant, tels que « qui suis-je » ou « lister mes portées ». Quelques-unes vont plus loin, et vous devriez les connaître avant d'activer les vérifications dans un environnement sensible :

  • Firebase Cloud Messaging envoie un message à un topic de test.
  • Les vérifications OAuth client-credential génèrent un token d'accès.
  • Certaines vérifications appellent un endpoint de vérification, tel que le runner verify de GitLab ou la clé de vérification de NuGet.
  • Les identifiants AWS SES sont vérifiés via SMTP sur le port 465, ce qu'un proxy ne couvre pas.

Certains analyseurs lisent des variables d'environnement telles que VAULT_ADDR, JENKINS_URL ou SONAR_HOST_URL pour atteindre un fournisseur Self-Hosted au lieu de la valeur publique par défaut. Définissez-les dans l'environnement de ggscout lorsque vos identifiants appartiennent à vos propres instances.

Proxys

L'étape de vérification ne passe pas par un proxy à une adresse privée. Avec un proxy configuré, les vérifications reviennent avec failed_to_check. Donnez à ggscout un chemin sortant direct vers les fournisseurs que vous souhaitez vérifier.

Activé par défaut, désactivable à tout moment​

Les vérifications s'exécutent à chaque fetch et fetch-and-send. Pour les désactiver, ajoutez une section [check] à votre configuration :

[check]
enabled = false

Avec le chart Helm, définissez-la sous inventory.config :

inventory:
config:
check:
enabled: false

Les secrets signalent alors not_checked (ou no_checker), et l'inventaire NHI affiche le dernier verdict reçu, le cas échéant. Voir Configurer les vérifications de validité pour les timeouts et la concurrence.

Nécessite ggscout 0.34.1 ou une version ultérieure

La validité, les permissions, le propriétaire et l'expiration nécessitent ggscout 0.34.1 ou une version ultérieure (chart Helm 0.5.23 ou une version ultérieure). Sur les versions antérieures, la validité de chaque secret stocké dans un vault reste Unknown dans l'inventaire NHI. Le paramètre de vérification de validité au niveau du workspace dans Settings > Secrets ne contrôle pas ggscout : utilisez [check].

Stocker en toute sécurité les secrets non stockés dans un vault​

Avec ggscout, vous pourrez identifier les secrets non stockés dans un vault à partir de votre liste d'incidents.
De plus, vous pourrez également pousser ces secrets dans vos gestionnaires de secrets et amorcer la remédiation de ces incidents !
Voici le scénario standard :

  • Une fois qu'un incident de secret est priorisé, vous pouvez insérer le secret dans votre gestionnaire de secrets
  • Vos développeurs corrigent leur code en invoquant correctement le secret depuis le bon chemin fourni dans le détail de l'incident de secret
  • Une fois la correction du code effectuée, révoquez le bon secret du vault à l'aide du lien hypertexte fourni dans le détail de l'incident de secret

ggscout prend en charge l'ensemble de ce processus à l'aide du flux simple suivant :

  1. ggscout récupère l'incident de secret qui n'a pas encore été stocké dans un vault.
  2. ggscout écrit le secret à l'emplacement spécifié.

Push-to-Vault

Cette fonctionnalité est facultative

Vous pouvez choisir de ne pas accorder d'accès en écriture.
Vous pouvez également restreindre les emplacements où le scout peut écrire des secrets (par exemple, un chemin temporaire spécifique à ggscout).

Conserver un contrôle total sur l'exécution de ggscout​

La transparence compte !

Aucune information sensible ne quitte jamais votre infrastructure.

Disposer d'un programme externe comme ggscout vous permet de :

  • Faire contrôler par votre équipe son exécution et ses accès (par exemple, avoir des accès partiels, avoir une instance pour l'accès en lecture et une autre pour l'accès en écriture)
  • Faire surveiller par votre équipe les données traitées

ggscout est auditable.

  • Vous pouvez exécuter le mode fetch-only et écrire un rapport JSON sur votre disque afin de pouvoir auditer les données collectées par ggscout, et vous assurer qu'aucune valeur de secret en clair n'est collectée. Les données disponibles dans le rapport correspondent exactement aux données envoyées à GitGuardian en mode par défaut.
  • Vous pouvez demander l'accès au code source

Démarrer​

Prêt à essayer ggscout ? Rendez-vous sur la page Déployer et configurer ggscout, qui inclut un guide de démarrage rapide pour les tests locaux avec le binaire CLI ou le package Python, ainsi que des options de déploiement en production à l'aide de Docker ou Kubernetes.

Pas d'accès à la plateforme GitGuardian ?​

Si vous déployez ggscout dans un cluster Kubernetes mais que vous n'avez pas accès à la plateforme GitGuardian, ce qui vous empêche d'envoyer les secrets hachés, ggbridge est la solution. Il établit une passerelle sécurisée, authentifiée par mTLS, entre votre réseau et la plateforme GitGuardian, permettant à ggscout de communiquer avec l'API publique de GitGuardian et de transmettre les données d'inventaire.

Pour des instructions de configuration détaillées et des informations complémentaires, veuillez consulter la documentation ggbridge.