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 via des appels API non intrusifs effectués vers 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 changé.
• 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'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 :

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 verront leur validité définie sur unknown puisque leur vérificateur de validité associé est désactivé. Réactiver le 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 le reste des détecteurs renverra 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 garder les vérifications de validité globalement désactivées, ces détecteurs seront désactivés et ne remonteront plus aucun incident.

Pour vérifier si un détecteur nécessite l'activation des vérifications de validité 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).

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 tous les secrets GitLab token détectés par rapport à votre environnement Self-Hosted.

Un endpoint de vérificateur de validité comprend :

• un hôte
• un chemin

Vous devez uniquement 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 devez simplement 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 le tableau 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.

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

Certains identifiants échappent aux 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 vous pouvez déterminer leur validité vous-même, avec vos propres outils, votre inventaire d'identifiants ou votre gestionnaire de secrets, vous pouvez remonter ce résultat à GitGuardian via l'API publique :

• Obtenir la validité d'un secret — lire la validité actuelle, et le statut que vous avez défini s'il en existe un.
• Remplacer la validité d'un secret — le déclarer valid, invalid ou failed_to_check selon votre propre vérification.
• Supprimer le remplacement de validité — rendre la gestion de 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 jeton d'accès personnel avec la portée secrets:write pour définir ou supprimer un statut, ou secrets:read pour en lire un — les portées secrets ne peuvent pas être accordées à un compte de service — et l'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 calcul de la sévérité et du 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, pas à 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é 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 depuis l'incident d'une seule équipe. Avant de remplacer un secret partagé, assurez-vous que la conclusion s'applique à chaque environnement où 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é.