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 à l'aide d'appels API non intrusifs adressés à l'hôte, si et quand cela est possible.

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

• valid : le secret peut encore ê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 allowlist d'adresses IP ou d'un autre mécanisme empêchant la vérification de validité. Cela peut aussi 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 secret :

Plan	Statut de l'incident	Ancienneté de l'incident	Fréquence
Business	Open	Moins d'un an	Quotidienne
Free	Open	Moins d'un an	Hebdomadaire
Business	Open	Plus d'un an	Hebdomadaire
Free	Open	Plus d'un an	Mensuelle
Business	Ignored	Moins d'un an	Mensuelle
Free	Ignored	Moins d'un an	Semestrielle
Business	Ignored	Plus d'un an	Semestrielle
Free	Ignored	Plus d'un an	Jamais
Business	Resolved	Moins d'un an	Mensuelle
Free	Resolved	Moins d'un an	Semestrielle
Business	Resolved	Plus d'un an	Semestrielle
Free	Resolved	Plus d'un an	Jamais

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

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, si et quand cela est possible.

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

attention

Cependant, veuillez noter que certains détecteurs nécessitent l'activation des vérifications de validité pour être actifs. Si vous choisissez de laisser les vérifications de validité globalement désactivées, ces détecteurs seront désactivés et ne déclencheront plus aucun incident.

Pour vérifier si un détecteur nécessite l'activation des vérifications de validité pour déclencher des incidents, accédez à 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).

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 par rapport à 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é par rapport à votre environnement Self-Hosted.

Un point de terminaison de vérificateur de validité comprend :

• un hôte
• un chemin

Vous n'avez besoin de fournir que 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.
Il vous suffit de 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.

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 par rapport au nouvel hôte. Cela garantit que vous disposez des informations de validité les plus précises.

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é pour les vérifications de validité.

Si vous êtes sous le plan Business, vous pouvez consulter la liste des détecteurs éligibles dans la table des détecteurs.

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

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

Par défaut, GitGuardian vérifie un secret par rapport à l'hôte par défaut de son détecteur et par rapport à chaque hôte personnalisé que vous ajoutez. Si votre équipe n'émet des identifiants que sur sa propre instance, la vérification par rapport à 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 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 uniquement par rapport à vos hôtes personnalisés.

1. Accédez à 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 apparaisse comme Valid URL response.
3. Désactivez le commutateur situé à côté de l'URL de l'hôte par défaut.

GitGuardian revérifie chaque secret du détecteur par rapport aux hôtes restants. Jusqu'à ce que cette vérification s'exécute, les incidents conservent la validité qu'ils avaient auparavant. Réactiver le commutateur déclenche la même revérification.

attention

Les secrets valides 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 y fonctionne. 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 valide.

Cela importe lorsque votre équipe utilise les deux hôtes. Si vous avez des projets sur gitlab.com et sur un GitLab Self-Hosted, un gitlab.com token divulgué reste exploitable, mais son incident cesse de l'indiquer. 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 ne dispose d'aucun hôte personnalisé valide : un secret n'aurait alors aucun hôte contre lequel être vérifié.
• Si vous supprimez le dernier hôte personnalisé valide, GitGuardian remet l'hôte par défaut à lui seul.
• Chaque modification est enregistrée dans votre journal d'audit sous la forme 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é par 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 l'hôte n'est accessible par aucun chemin réseau pour GitGuardian sont signalés comme failed to check. Aucun de ces statuts ne répond à la question que se pose votre équipe.

Si vous pouvez déterminer leur validité vous-même, avec vos propres outils, votre inventaire d'identifiants ou votre gestionnaire de secrets, vous pouvez signaler ce résultat à GitGuardian via l'API publique :

• Obtenir la validité d'un secret — lisez la validité actuelle, ainsi que le statut que vous avez défini s'il en existe un.
• Remplacer la validité d'un secret — déclarez-le valid, invalid ou failed_to_check d'après votre propre vérification.
• Supprimer le remplacement de validité — redonnez la validité à GitGuardian.

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 personal access token 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 service account — ainsi que d'un accès à l'incident auquel appartient le secret.

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 scoring de sévérité et de risque, les playbooks, les notifications et les exports. Tant qu'il est défini, GitGuardian met en pause ses propres vérifications périodiques sur ce secret. Le supprimer restaure le dernier statut que GitGuardian avait lui-même déterminé 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.

attention

Un statut de validité personnalisé s'applique au secret, et non à l'incident depuis lequel 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é adopte 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 depuis l'incident d'une seule équipe. Avant de remplacer la validité d'un secret partagé, assurez-vous que la conclusion vaut pour chaque environnement dans lequel il est utilisé — un identifiant peut être révoqué sur un hôte et rester actif sur un autre.

info

Le secret doit être rattaché à au moins un incident Internal Monitoring auquel vous avez accès. 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é.