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 fuite 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 prend du temps et est 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. Classant 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 il appartient 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 capacités clés :

1. Étendre la couverture de détection

En maintenant un inventaire des secrets stockés dans le coffre-fort, 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 coffre-fort.

Exemple : un développeur commit 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 le coffre-fort sont accompagnés de métadonnées précieuses : chemins du coffre-fort, 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 fuitent. 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 en premier le secret de production.

3. Amorcer la remédiation des incidents

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

Exemple : GitGuardian détecte un mot de passe de base de données codé en dur dans un ancien dépôt. À l'aide de ggscout, vous pouvez pousser ce secret vers votre coffre-fort et fournir aux développeurs le chemin exact pour le référencer, rationalisant 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 telles que les noms des secrets, les chemins dans le coffre-fort, 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 en toute sécurité les secrets pour faciliter la remédiation des incidents

Une fois ggscout déployé et configuré dans votre environnement, il fonctionne 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 classe chaque valeur avec le Secrets Detection Engine.
3. Il vérifie chaque secret classé 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.

C'est tout, vous pouvez commencer à tirer parti de ces capacités depuis votre plateforme GitGuardian !

Classer les secrets avec le Secrets Detection Engine

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

La classification est basée 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 attache ce détecteur au secret. GitGuardian en déduit alors le type de détecteur (générique ou spécifique), la famille de secret, 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 écarté.

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

• Un fichier en texte clair tel qu'un .env est découpé en une entrée d'inventaire par secret détecté, chacune avec son propre hachage, afin de pouvoir être corrélée avec les fuites de ces tokens.
• Les champs frères qui forment un même identifiant (par exemple un nom d'utilisateur et un mot de passe dans le même objet de coffre-fort) sont classé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 une fois qu'elle est publiée. 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 une valeur classé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 scopes ou permissions indiqués par le fournisseur, comme repo et admin:org pour un token GitHub.
• À qui appartient-il ? Le compte côté fournisseur derrière l'identifiant, avec son statut admin lorsque le fournisseur l'expose.
• Quand expire-t-il ? La date d'expiration, lorsque le fournisseur en définit une.

Les réponses sont envoyées à GitGuardian avec le secret haché et apparaissent dans l'inventaire NHI sous la forme d'une colonne et d'un filtre Validity, ainsi que des permissions, du propriétaire et de l'expiration dans le détail de l'identité. Lorsque le même secret figure aussi dans un incident de secret, GitGuardian fusionne les deux verdicts et conserve le plus récent.

ggscout utilise les mêmes checkers de validité et analyseurs de secrets que la plateforme GitGuardian. Chaque vérification s'exécute après une nouvelle récupération, de sorte qu'un verdict n'est jamais plus ancien que la planification de vos exécutions.

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

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

• 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 de votre réseau. Depuis les serveurs de GitGuardian, ces vérifications renvoient Failed to check.
• Aucune 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 collecté par ggscout, et pas seulement sur ceux qui apparaissent aussi dans un incident. Vous obtenez la liste des identifiants révoqués encore présents dans vos coffres-forts, ainsi que ceux qui sont surprivilégiés, sans attendre une fuite.
• Fraîcheur : les verdicts sont actualisés à chaque exécution, selon la planification que vous contrôlez.

Ce qui est envoyé à GitGuardian

Uniquement le résultat : un statut de validité, la liste triée des scopes, l'identité du propriétaire indiquée par le fournisseur (ID utilisateur, e-mail, indicateur admin), 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 du fournisseur. La valeur du secret reste dans votre réseau et est hachée comme d'habitude.

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

Statut	Signification
valid	Le fournisseur a accepté l'identifiant.
invalid	Le fournisseur l'a rejeté : révoqué, expiré ou incorrect.
failed_to_check	Une vérification a été exécutée mais n'a pas pu conclure : délai dépassé, erreur réseau, limite de débit ou accès refusé.
not_checked	Un checker existe pour ce détecteur mais ne s'est pas exécuté, par exemple parce que l'étape est désactivée.
no_checker	Aucun détecteur ne correspond, ou le détecteur n'a pas de checker.

Ce que fait la vérification chez le fournisseur

La plupart des vérifications sont des appels en lecture seule via HTTPS sortant, comme « qui suis-je » ou « liste mes scopes ». Quelques-unes vont plus loin, et vous devez 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 d'identifiants client OAuth génèrent un token d'accès.
• Certaines vérifications appellent un endpoint de vérification, comme 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, qui n'est pas couvert par un proxy.

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.

Proxies

L'étape de vérification ne passe pas par un proxy situé à une adresse privée. Si un tel proxy est configuré, les vérifications renvoient 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 renvoient alors not_checked (ou no_checker), et l'inventaire NHI affiche le dernier verdict reçu, le cas échéant. Consultez Configurer les vérifications de validité pour les délais d'expiration 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 ultérieur). Sur les versions antérieures, la validité de chaque secret stocké dans un coffre-fort 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 le coffre-fort

Avec ggscout, vous pourrez identifier les secrets non stockés dans le coffre-fort depuis votre liste d'incidents.
De plus, vous pourrez également pousser ces secrets vers 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 coffre-fort à 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 le coffre-fort.
2. ggscout écrit le secret à l'emplacement spécifié.

Cette capacité est facultative

Vous pouvez choisir de ne pas accorder l'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 son exécution et ses accès par votre équipe (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 sont exactement les 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 supplémentaires, veuillez consulter la documentation ggbridge.