Détecter les secrets dans les PR GitHub

Vue d'ensemble

Les GitHub Check Runs seront déclenchés sur les pull requests GitHub des dépôts surveillés par GitGuardian. Les scans de secrets dans le cadre des GitHub Check Runs s'exécuteront côté serveur sur le VCS, à l'étape post-receive.

Les scans de secrets de GitGuardian s'exécutent sur chaque commit individuel qui compose la pull request, et pas seulement sur l'état final du code dans la pull request. Ce scan en profondeur permet de découvrir les cas où un commit A ajoute un secret et un commit B retire le même secret au sein de la même pull request.

Cela permet au développeur individuel d'être notifié lorsqu'un incident est détecté par GitGuardian, directement dans l'interface GitHub. Ceci est particulièrement utile lorsqu'un développeur ouvre une pull request pour fusionner une branche individuelle dans une branche collaborative. Le Check Run alertera le développeur avant que les commits ne soient fusionnés, limitant l'incident à sa branche et lui offrant l'opportunité d'une remédiation plus facile. Le résultat est des branches collaboratives exemptes de secrets, telles que celles utilisées pour les environnements de QA, de staging et de production.

À quoi cela ressemble

Dans l'interface GitHub, un check run GitGuardian présente un tableau avec toutes les découvertes et leurs détails pertinents :

• l'id de l'incident de secret correspondant sur GitGuardian
• le statut de l'incident de secret correspondant sur GitGuardian
  Gardez à l'esprit que si les incidents de secrets sont fermés sur le Dashboard GitGuardian, ils ne seront plus signalés par les checkruns GitHub.
• le type de secret
• le sha du commit
• le nom du fichier
• ainsi que des liens vers le Dashboard GitGuardian si l'utilisateur souhaite y consulter l'incident et agir dessus (changer le statut, laisser des notes, résoudre, etc.).

Les incidents de secrets détectés lors des check runs et signalés dans le Dashboard GitGuardian renvoient également à la pull request GitHub d'origine.

Veuillez noter que seules les pull requests GitHub créées après le 10 février 2022 seront visibles.

Gérer vos GitHub check runs

Activer ou désactiver les check runs GitGuardian

En tant que Manager du workspace, vous pouvez décider d'activer ou de désactiver les GitHub Check Runs pour les dépôts surveillés directement dans votre page de paramètres GitHub ou votre page de paramètres GitHub Enterprise Server.

Note : Si vous avez intégré à la fois GitHub.com et GitHub Enterprise Server, vous aurez deux paramètres de check runs différents.

Choisir la conclusion des check runs lorsque des secrets sont détectés

Vous avez également la possibilité de déterminer la conclusion des check runs GitHub lorsque des secrets sont détectés. Vous pouvez choisir entre deux options :

• soit Failed
  Cette conclusion empêchera vos développeurs de fusionner la pull request si vous avez mis en place des branches protégées, garantissant que vos secrets ne se retrouvent pas en production.
  Pour éviter les blocages complets, GitGuardian fournit des boutons d'action skip permettant aux développeurs de contourner les check runs bloquants. Plus de détails ci-dessous.
• soit Neutral
  Cette conclusion ne bloque pas les pull requests.
  Les développeurs seront notifiés de la présence de secrets, surtout si vous activez GitGuardian pour publier un commentaire afin d'améliorer la visibilité des secrets détectés dans la pull request. Référez-vous à la section ci-dessous pour plus d'informations.

Ignorer les commits de merge dans les check runs des pull requests

Par défaut, les check runs scannent chaque commit qui compose une pull request, y compris les commits de merge qui intègrent des modifications depuis la branche cible. Cela peut faire remonter des secrets qui n'ont pas été introduits sur la branche de la PR elle-même, entraînant des faux positifs que l'auteur de la PR ne peut pas remédier.

En tant que Manager du workspace, vous pouvez activer Skip merge commits in pull request check runs dans votre page de paramètres GitHub ou votre page de paramètres GitHub Enterprise Server. Lorsque cette option est activée, les check runs ignorent les commits de merge et ne signalent que les secrets introduits par les commits créés sur la branche de la PR.

Activer ou désactiver les actions skip

Lorsque la conclusion des checkruns en cas de détection de secrets est « Failed », les pull requests ne peuvent pas être fusionnées. Cependant, comme la détection des secrets est probabiliste, GitGuardian propose des boutons d'action skip pour éviter d'entraver complètement les développeurs.
Ces actions skip reflètent les raisons d'ignorance disponibles sur le dashboard, étant entendu qu'ignorer un checkrun contenant un secret revient à ignorer l'incident associé. Les actions skip disponibles incluent :

• Skip: false positive
• Skip: test credential
• Skip: low risk

Lorsqu'une action skip est effectuée, l'incident de secret correspondant est tagué pour informer les utilisateurs du dashboard qu'un développeur a intentionnellement ignoré le checkrun après avoir rencontré l'alerte de secret. Les tags pour les incidents ignorés incluent :

• Skipped in check run as false positive
• Skipped in check run as test credential
• Skipped in check run as low risk

En tant que Manager du workspace, vous avez la possibilité de désactiver entièrement la capacité d'ignorer les check runs dans vos paramètres.

Publier un commentaire dans la timeline de la pull request

Pour étendre la visibilité des résultats des checkruns et s'assurer que vos développeurs ne les manquent pas, GitGuardian publie un commentaire lorsqu'un secret est détecté.

Ce comportement peut être activé ou désactivé dans vos paramètres par les Managers du workspace :

Personnaliser les directives de remédiation

En tant que Manager du workspace, vous pouvez personnaliser les directives de remédiation. Ces directives seront affichées dans l'interface GitHub à la fois dans le corps du check run et dans le commentaire publié sur la timeline de la pull request.

Utiliser des liens de partage publics pour les détails des incidents

Lorsqu'ils sont activés, les check runs généreront automatiquement des liens de partage publics permettant aux développeurs d'accéder aux détails des incidents et de les résoudre directement depuis l'interface de la pull request, sans nécessiter d'accès au Dashboard GitGuardian.

Ce comportement fonctionne en conjonction avec le playbook « Auto-share incident access to the author of the leak » : les liens de partage publics sont utilisés lorsque l'incident est créé par un non-membre du workspace avec une adresse e-mail non générique, tandis que les membres du workspace reçoivent des URL authentifiées vers le Dashboard GitGuardian. Cela nécessite que le playbook Auto-share incident access et la capacité de partage public soient activés. Les liens de partage héritent des mêmes contrôles de sécurité et délais d'expiration que le playbook auto-share.

En tant que Manager du workspace, vous pouvez activer ou désactiver cette fonctionnalité dans vos paramètres GitHub.

Dépendances

Protection des branches GitHub : rulesets vs branch protection rules

GitHub propose deux façons de protéger vos branches : les rulesets et les branch protection rules. Comprendre la différence est important lors de la configuration des check runs GitGuardian :

Utilisation des rulesets

Si vous utilisez un ruleset et exigez que les contrôles de sécurité GitGuardian soient validés :

• Vous devez également activer "Require a pull request before merging". Sans ce paramètre, GitHub bloquera tout push effectué directement sur la branche protégée, car les rulesets s'appliquent à tous les commits, y compris les pushes directs.
• Votre dépôt doit être activement surveillé par GitGuardian. Si ce n'est pas le cas, GitHub attendra un check run de GitGuardian qui ne sera jamais fourni, provoquant un check run en attente perpétuel.
• Si la conclusion du check run est Failed, GitHub affichera un avertissement spécifique. La conclusion Neutral est considérée comme équivalente à un check run réussi.

Utilisation des branch protection rules

Si vous utilisez des branch protection rules avec le paramètre "Require status checks to pass before merging" :

• Les branch protection rules ne s'appliquent qu'aux pull requests, pas aux pushes directs sur la branche, elles fonctionnent donc parfaitement avec les check runs GitGuardian sans configuration supplémentaire.
• Votre dépôt doit être activement surveillé par GitGuardian.
  Si ce n'est pas le cas, GitHub attendra un check run de GitGuardian qui ne sera jamais fourni, provoquant un check run en attente perpétuel.
  
• Si la conclusion du check run est Failed, GitHub affichera un avertissement spécifique.
  La conclusion Neutral est considérée comme équivalente à un check run réussi.
  

Travailler avec des dépôts forkés

Dans un processus de fork, il y a deux dépôts :

1. Dépôt forké : Votre copie personnelle du dépôt upstream, marquée comme fork = true sur GitHub.
2. Dépôt upstream : Le dépôt d'origine.

Dépôts forkés

Par défaut, GitGuardian ne génère pas de check runs sur les dépôts forkés surveillés afin d'éviter les erreurs de limitation de débit.

Ce problème survient car de nombreux dépôts forkés génèrent automatiquement de nombreuses pull requests pour rester à jour avec leurs dépôts upstream, qui ont souvent un niveau d'activité élevé. Ces pull requests automatisées sont gourmandes en ressources et peuvent entraîner des erreurs de limitation de débit lors des check runs GitGuardian.

Cependant, les Managers des workspaces du plan Business ont la possibilité d'activer les check runs GitGuardian sur leurs dépôts forkés surveillés.

Dépôts upstream

Les check runs sont créés sur les dépôts upstream surveillés.
Cependant, lorsqu'une pull request provenant d'un dépôt forké contient des secrets, GitGuardian ne peut pas proposer les boutons d'actions « Skip » habituels. Dans ce scénario, GitGuardian fournit un simple bouton Skip pour éviter de bloquer le développeur.

Prise en charge de GitHub Merge Queue

Lorsqu'une pull request est ajoutée à une merge queue GitHub, GitGuardian répond par un check run neutre car :

• Le scan des secrets est déjà effectué sur les pull requests avant qu'elles n'entrent dans la merge queue
• La merge queue ne crée pas de nouveaux commits susceptibles d'introduire de nouveaux secrets
• Les PR doivent passer les check runs GitGuardian avant d'être éligibles à la merge queue

Ce statut neutre ne bloquera pas la validation de la merge queue, même si le check GitGuardian est marqué comme requis.

Pull requests très volumineuses

Étant donné qu'un check run scanne chaque commit d'une pull request via l'API GitHub, les pull requests très volumineuses peuvent générer un volume élevé d'appels API. L'installation GitHub App a une limite de débit partagée de 5 000 requêtes par heure pour l'ensemble de votre organisation (voir les limites de débit de GitHub), et une seule pull request surdimensionnée pourrait la consommer.

Pour protéger le budget API de votre organisation, GitGuardian ignore le scan check-run sur les pull requests dépassant une limite de taille configurée. Auparavant, ces pull requests ne se scannaient pas avec succès — elles expiraient ou échouaient. L'ignorance ne s'applique qu'aux pull requests au-delà de la limite, elle est donc peu fréquente, et le résultat est visible en tant que statut du check run sur la pull request dans GitHub.

Aller plus loin : personnaliser les check runs par dépôt

GitGuardian vous offre la possibilité de personnaliser le comportement des check runs GitGuardian au niveau du dépôt en utilisant les fonctionnalités natives de GitHub pour remplacer la configuration définie sur le Dashboard GitGuardian.

Utilisation des custom properties GitHub

Les custom properties GitHub vous permettent de personnaliser les check runs à la fois au niveau de l'organisation et au niveau du dépôt :

• si le checkrun est présent ou non
• spécifier la conclusion comme Failed ou Neutral lorsque des secrets sont détectés.
• si les actions skip sont disponibles ou non.

Il est crucial d'utiliser les noms exacts des custom properties indiqués ci-dessous pour garantir le bon fonctionnement de la fonctionnalité.

Remplacer la présence des check runs

Types de propriétés pris en charge : (Text, Single select, True/False)

Configuration globale GitGuardian	Custom property gitguardian-check-runs-enabled
	true	false	null
Les check runs sont activés ✅	les check runs seront présents ✅	les check runs ne seront pas présents 🚫	les check runs seront présents ✅
Les check runs sont désactivés 🚫	les check runs seront présents ✅	les check runs ne seront pas présents 🚫	les check runs ne seront pas présents 🚫

Remplacer la conclusion des check runs

Types de propriétés pris en charge : (Text, Single select)

Configuration globale GitGuardian	Custom property gitguardian-check-runs-secrets-conclusion
	neutral	failed	null ou autre
Conclusion des check runs si des secrets sont Neutral ⬛	la conclusion des check runs si des secrets sera Neutral ⬛	la conclusion des check runs si des secrets sera Failed ❌ (bloque la PR)	la conclusion des check runs si des secrets sera Neutral ⬛
Conclusion des check runs si des secrets sont Failure ❌	la conclusion des check runs si des secrets sera Neutral ⬛	la conclusion des check runs si des secrets sera Failed ❌ (bloque la PR)	la conclusion des check runs si des secrets sera Failed ❌ (bloque la PR)

Remplacer la présence des actions skip des check runs lorsque la conclusion est Failed

Types de propriétés pris en charge : (Text, Single select, True/False)

Configuration globale GitGuardian	Custom property gitguardian-check-runs-actions-enabled
	true	false	null
Les boutons d'action skip sont activés ✅	les boutons d'action skip seront présents ✅	les boutons d'action skip ne seront pas présents 🚫	les boutons d'action skip seront présents ✅
Les boutons d'action skip sont désactivés 🚫	les boutons d'action skip seront présents ✅	les boutons d'action skip ne seront pas présents 🚫	les boutons d'action skip ne seront pas présents 🚫

Utilisation des labels GitHub pour GitHub Enterprise Server < 3.13

attention

L'utilisation des labels GitHub pour personnaliser les check runs est dépréciée et sera supprimée en janvier 2026.
Veuillez migrer vers les Custom properties qui sont disponibles à partir de la version 3.13 de GitHub Enterprise Server.

Veuillez contacter votre account manager pour faire activer cette fonctionnalité.

Sur GitHub Enterprise Server < 3.13, les labels GitHub vous permettent de personnaliser les check runs au niveau du dépôt :

• si le check run est présent ou non.
• spécifier la conclusion comme Failed ou Neutral lorsque des secrets sont détectés.
• si les actions skip sont disponibles ou non.

Vous êtes libre de personnaliser la description et la couleur du label, mais il est essentiel que le nom du label reste exact.

Remplacer la présence des check runs

Configuration globale GitGuardian	Labels du dépôt GitHub Enterprise Server
	gitguardian:check-runs-enabled	gitguardian:check-runs-disabled	Aucun label	Les deux labels présents
Les check runs sont activés ✅	les check runs seront présents ✅	les check runs ne seront pas présents 🚫	les check runs seront présents ✅	les check runs seront présents ✅
Les check runs sont désactivés 🚫	les check runs seront présents ✅	les check runs ne seront pas présents 🚫	les check runs ne seront pas présents 🚫	les check runs seront présents ✅

Remplacer la conclusion des check runs

Configuration globale GitGuardian	Labels du dépôt GitHub Enterprise Server
	gitguardian:check-runs-secrets-conclusion-neutral	gitguardian:check-runs-secrets-conclusion-failed	Aucun label	Les deux labels présents
Conclusion des check runs si des secrets sont Neutral ⬛	la conclusion des check runs si des secrets sera Neutral ⬛	la conclusion des check runs si des secrets sera Failed ❌ (bloque la PR)	la conclusion des check runs si des secrets sera Neutral ⬛	la conclusion des check runs si des secrets sera Neutral ⬛
Conclusion des check runs si des secrets sont Failure ❌	la conclusion des check runs si des secrets sera Neutral ⬛	la conclusion des check runs si des secrets sera Failed ❌ (bloque la PR)	la conclusion des check runs si des secrets sera Failed ❌ (bloque la PR)	la conclusion des check runs si des secrets sera Neutral ⬛

Remplacer la présence des actions skip des check runs lorsque la conclusion est Failed

Configuration globale GitGuardian	Labels du dépôt GitHub Enterprise Server
	gitguardian:check-runs-actions-enabled	gitguardian:check-runs-actions-disabled	Aucun label	Les deux labels présents
Les boutons d'action skip sont activés ✅	les boutons d'action skip seront présents ✅	les boutons d'action skip ne seront pas présents 🚫	les boutons d'action skip seront présents ✅	les boutons d'action skip seront présents ✅
Les boutons d'action skip sont désactivés 🚫	les boutons d'action skip seront présents ✅	les boutons d'action skip ne seront pas présents 🚫	les boutons d'action skip ne seront pas présents 🚫	les boutons d'action skip seront présents ✅