Aller au contenu principal

Vérifications de validité

Fonctionnement des vérifications de validité​

Pour vous fournir des alertes de haute précision, GitGuardian tente de vérifier la validité des secrets grâce à des appels d'API non intrusifs effectués vers l'hôte, lorsque cela est possible.

Secret validity preview and filter

La vérification de validité peut renvoyer 5 valeurs possibles :

  • valid : le secret peut toujours être exploité et doit être révoqué et renouvelé.
  • invalid : le secret a été révoqué.
  • failed to check : GitGuardian n'a pas pu déterminer la validité du secret. Cela se produit lorsqu'il n'est pas possible de distinguer l'erreur causée par un secret invalide d'une liste d'autorisation d'adresses IP ou d'un autre mécanisme empêchant la vérification de validité. Cela peut également signifier que le fournisseur de service est temporairement indisponible.
  • cannot check : le fournisseur de service ou le type de secret ne permet pas les vérifications par GitGuardian. Ce statut s'affiche également lorsque les vérifications de validité des secrets sont désactivées par un Manager du workspace.
  • unknown : GitGuardian a récemment introduit un vérificateur de validité, la validité de ce secret n'a pas encore été vérifiée.

GitGuardian exécute automatiquement les vérifications de validité des secrets en arrière-plan. La fréquence de ces vérifications dépend de votre plan ainsi que du statut et de l'ancienneté des incidents de secrets :

PlanStatut de l'incidentAncienneté de l'incidentFréquence
Growth et EnterpriseOpenMoins d'un anQuotidienne
FreeOpenMoins d'un anHebdomadaire
Growth et EnterpriseOpenPlus d'un anHebdomadaire
FreeOpenPlus d'un anMensuelle
Growth et EnterpriseIgnoredMoins d'un anMensuelle
FreeIgnoredMoins d'un anSemestrielle
Growth et EnterpriseIgnoredPlus d'un anSemestrielle
FreeIgnoredPlus d'un anJamais
Growth et EnterpriseResolvedMoins d'un anMensuelle
FreeResolvedMoins d'un anSemestrielle
Growth et EnterpriseResolvedPlus d'un anSemestrielle
FreeResolvedPlus d'un anJamais

Si vous utilisez GitGuardian Self-Hosted, vous pouvez modifier ces fréquences dans votre espace d'administration.

Les secrets dans un coffre sont vérifiés depuis l'intérieur de votre réseau

Les secrets collectés par ggscout sont vérifiés par ggscout lui-même, à chaque exécution, avec les mêmes vérificateurs. Parce que la vérification s'exécute à côté du secret, elle atteint les fournisseurs et services Self-Hosted que les serveurs de GitGuardian ne peuvent pas atteindre, et elle couvre chaque secret dans un coffre, pas seulement ceux associés à un incident. Le verdict s'affiche dans l'inventaire NHI. Consultez Vérifier la validité et les permissions à la source.

Activer et désactiver les vérifications de validité​

Il est possible de désactiver les vérifications de validité pour l'ensemble du workspace GitGuardian.

Les nouveaux secrets qui pourraient être marqués comme valid ou invalid auront leur validité définie sur unknown puisque leur vérificateur de validité associé est désactivé. La réactivation du vérificateur de validité déclenchera le processus de vérification sur tous les incidents existants, lorsque cela est possible.

Secrets detection settings

Veuillez noter que ces paramètres s'appliquent également à l'API et à ggshield. Les détecteurs nécessitant que les vérifications de validité soient activées pour être actifs seront désactivés et les autres détecteurs renverront la valeur unknown pour les vérifications de validité des secrets.

Ce paramètre ne s'applique pas aux vérifications que ggscout exécute sur les secrets dans un coffre. Celles-ci sont contrôlées par la section [check] de la configuration ggscout.

attention

Veuillez toutefois noter que certains détecteurs nécessitent que les vérifications de validité soient activées pour être actifs. Si vous choisissez de garder les vérifications de validité désactivées globalement, ces détecteurs seront désactivés et ne remonteront plus aucun incident.

Pour vérifier si un détecteur nécessite que les vérifications de validité soient activées pour remonter des incidents, rendez-vous sur la page dédiée du détecteur dans la documentation Secrets Detection et recherchez l'indicateur Only valid secrets raise an alert: True (ex : Agora API keys).

Secret detector only valid true

Personnaliser les vérifications de validité​

GitGuardian permet de personnaliser les vérifications de validité pour certains détecteurs en spécifiant un hôte personnalisé.

Prenons le détecteur GitLab token. Par défaut, il vérifie les secrets auprès de gitlab.com (GitLab SaaS). Cependant, si vous disposez d'une instance GitLab Self-Hosted, vous pouvez fournir l'URL de votre instance. GitGuardian vérifiera alors tout secret GitLab token détecté auprès de votre environnement Self-Hosted.

Un endpoint de vérificateur de validité comprend :

  • un hôte
  • un chemin

Vous n'avez qu'à fournir l'hôte. GitGuardian utilise le même chemin que l'hôte par défaut pour la vérification personnalisée.

Supposons donc que le vérificateur de validité du GitLab token soit https://gitlab.com/the-route-to-check-the-validity.
Vous n'avez qu'à fournir l'hôte (ex : https://my_gitlab.self_hosted_instance.corp) et GitGuardian construit le vérificateur de validité https://my_gitlab.self_hosted_instance.corp/the-route-to-check-the-validity.

Secret detector custom host

Lorsque vous soumettez un hôte personnalisé pour les vérifications de validité, tous les secrets précédemment détectés pour ce détecteur seront revérifiés auprès du nouvel hôte. Cela garantit que vous disposez des informations de validité les plus précises.

Secret valid on custom host

info

Seuls les détecteurs qui prennent en charge les vérifications de validité et qui possèdent l'attribut On-premise instance exist: True peuvent être personnalisés avec une URL d'hôte personnalisée pour les vérifications de validité.

Secret detector eligible for custom host

Si vous êtes sous le plan Growth ou Enterprise, vous pouvez consulter la liste des détecteurs éligibles dans le tableau des détecteurs.

Table of detectors eligible for custom host

Les hôtes personnalisés pour les vérifications de validité ne sont disponibles que pour les workspaces sous notre plan Enterprise.

Exclure l'hôte par défaut des vérifications de validité​

Par défaut, GitGuardian vérifie un secret auprès de l'hôte par défaut de son détecteur et auprès de chaque hôte personnalisé que vous ajoutez. Si votre équipe ne délivre jamais d'identifiants que sur votre propre instance, la vérification auprès de l'hôte public du fournisseur n'apporte rien. Elle échoue également lorsque votre déploiement ne peut pas atteindre cet hôte, par exemple sur un réseau isolé (air-gapped).

Pour un détecteur qui prend en charge les hôtes personnalisés, vous pouvez exclure l'hôte par défaut. GitGuardian vérifie alors les secrets de ce détecteur auprès de vos hôtes personnalisés uniquement.

  1. Allez dans Settings > Secrets > Detectors et ouvrez le détecteur.
  2. Sous Validity check host(s), ajoutez un hôte personnalisé si vous n'en avez pas encore. Il doit être actif et répondre au ping, afin qu'il s'affiche comme Valid URL response.
  3. Désactivez l'interrupteur à côté de l'URL de l'hôte par défaut.

Default host left out of validity checks, with one valid custom host

GitGuardian revérifie chaque secret du détecteur auprès des hôtes restants. Tant que cette vérification ne s'exécute pas, les incidents conservent la validité qu'ils avaient auparavant. Réactiver l'interrupteur déclenche la même revérification.

attention

Les secrets qui sont valid sur l'hôte par défaut perdent cette validité.

Une fois l'hôte par défaut exclu, GitGuardian ne sait plus si un secret fonctionne sur celui-ci. La validité d'un secret reflète uniquement vos hôtes personnalisés, de sorte qu'un secret actif sur l'hôte par défaut mais pas sur votre hôte personnalisé n'est plus signalé comme valid.

Cela compte lorsque votre équipe utilise les deux hôtes. Si vous avez des projets sur gitlab.com et sur un GitLab Self-Hosted, un token gitlab.com divulgué reste exploitable, mais son incident cesse de le montrer. Conservez l'hôte par défaut pour les détecteurs dont les identifiants des deux hôtes peuvent apparaître dans votre périmètre.

Quelques règles s'appliquent :

  • Vous ne pouvez pas exclure l'hôte par défaut tant que le détecteur n'a pas d'hôte personnalisé valide : un secret n'aurait aucun hôte auprès duquel être vérifié.
  • Si vous supprimez le dernier hôte personnalisé valide, GitGuardian réactive l'hôte par défaut tout seul.
  • Chaque modification est enregistrée dans votre journal d'audit sous default_host_enabled ou default_host_disabled.
info

L'exclusion de l'hôte par défaut est disponible pour les workspaces sous notre plan Business, sur les détecteurs qui prennent en charge les hôtes personnalisés.

Définir votre propre statut de validité via l'API​

Certains identifiants sont hors de portée des vérifications de GitGuardian. Les secrets appartenant à vos services internes, à vos plateformes maison et à vos API propriétaires, ou détectés par vos propres détecteurs personnalisés, n'ont aucun vérificateur de validité : ils sont signalés comme cannot check. Les secrets dont GitGuardian n'a aucun chemin réseau vers l'hôte sont signalés comme failed to check. Aucun de ces statuts ne répond à la question que se pose votre équipe.

Si le secret réside dans un gestionnaire de secrets, une CI ou un cluster que ggscout collecte, ggscout le vérifie depuis votre réseau et vous en rapporte le résultat. Pour les autres, si vous pouvez déterminer leur validité vous-même, avec votre propre outillage ou votre inventaire d'identifiants, vous pouvez rapporter ce résultat à GitGuardian via l'API publique :

Consultez la référence de l'API publique pour les détails des requêtes et des réponses. Vous avez besoin d'un jeton d'accès personnel avec le scope secrets:write pour définir ou supprimer un statut, ou secrets:read pour en lire un — les scopes secrets ne peuvent pas être accordés à un compte de service — et un accès à l'incident auquel le secret appartient.

Le statut que vous définissez devient la validité du secret partout où GitGuardian utilise la validité : la liste des incidents et les filtres de validité, le score de sévérité et de risque, les playbooks, les notifications et les exports. Tant qu'il est défini, GitGuardian suspend ses propres vérifications périodiques sur ce secret. Le supprimer restaure le dernier statut que GitGuardian avait déterminé lui-même et déclenche une nouvelle vérification.

Sur l'incident, le champ est intitulé Custom validity avec la date à laquelle il a été défini, afin que votre équipe puisse distinguer votre résultat de celui de GitGuardian. La définition et la suppression sont enregistrées dans le journal d'activité de l'incident et dans votre journal d'audit.

Custom validity on the secret details of an incident

attention

Un statut de validité personnalisé s'applique au secret, pas à l'incident à partir duquel vous le définissez.

La validité est une propriété de l'identifiant lui-même. Si le même secret a été détecté dans plusieurs dépôts, chaque incident qui lui est lié prend le statut que vous définissez, dans Internal Monitoring comme dans Public Monitoring, et à travers les périmètres d'équipe.

Il n'existe pas de remplacement par équipe : en définir un est une décision à l'échelle du workspace, même lorsqu'elle est prise à partir de l'incident d'une seule équipe. Avant de remplacer un secret partagé, assurez-vous que la conclusion est valable pour chaque environnement dans lequel il est utilisé — un identifiant peut être révoqué sur un hôte et toujours actif sur un autre.

info

Le secret doit être rattaché à au moins un incident Internal Monitoring auquel vous pouvez accéder. Un secret qui n'existe que dans Public Monitoring ne peut pas être la cible d'un statut de validité personnalisé. Lorsque le même secret existe dans les deux, le statut s'applique au secret lui-même, de sorte que l'incident Public Monitoring affiche également la validité personnalisée.

Les statuts personnalisés sont définis un secret par appel. GitGuardian n'exécute pas votre vérification à votre place, il enregistre le résultat que vous avez déterminé.