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 analyses de secrets dans le contexte des GitHub Check Runs seront exécutées côté serveur sur le VCS, à l'étape post-receive.
Les analyses de secrets GitGuardian s'exécutent sur chaque commit individuel composant la pull request, et pas seulement sur l'état final du code dans la pull request. Cette analyse approfondie aide à découvrir les cas où un commit A ajoute un secret et un commit B supprime 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. C'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 donnant l'opportunité d'une remédiation plus facile. Le résultat est des branches collaboratives sans secrets telles que celles utilisées pour les environnements QA, staging et production.
À quoi ça ressemble
Dans l'UI GitHub, un check run GitGuardian présente une table 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 remontés par les checkruns GitHub. - le type de secret
- le sha du commit
- le nom de fichier
- et également des liens vers le dashboard GitGuardian si l'utilisateur souhaite y voir l'incident et agir dessus (changer le statut, laisser des notes, résoudre, etc.).
Les incidents de secrets détectés pendant les check runs et remontés dans le dashboard GitGuardian renvoient également vers 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 check runs GitHub
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 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 des branches protégées en place, garantissant que vos secrets n'arrivent pas en production.
Pour éviter les blocages complets, GitGuardian fournit des boutons skip action 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.
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 de secrets est probabiliste, GitGuardian propose des boutons skip action pour éviter d'entraver complètement les développeurs.
Ces actions skip reflètent les raisons d'ignorance disponibles sur le dashboard, étant entendu que skipper un checkrun contenant un secret revient à ignorer l'incident associé. Les actions skip disponibles incluent :
Skip: false positiveSkip: test credentialSkip: 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 skippé le checkrun après avoir rencontré l'alerte de secret. Les tags pour les incidents skippés incluent :
Skipped in check run as false positiveSkipped in check run as test credentialSkipped in check run as low risk
En tant que workspace manager, vous avez la possibilité de désactiver entièrement la capacité de skipper les check runs dans vos paramètres.
Publier un commentaire dans la timeline de la pull request
Pour étendre la visibilité des résultats de checkrun et garantir que vos développeurs ne le 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 guidelines de remédiation
En tant que Manager du workspace, vous pouvez personnaliser les guidelines de remédiation. Ces guidelines 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 les liens de partage publics pour les détails d'incident
Lorsqu'ils sont activés, les check runs généreront automatiquement des liens de partage publics qui permettent aux développeurs d'accéder et de résoudre les détails d'incident directement depuis l'interface de la pull request, sans nécessiter d'accès au dashboard GitGuardian.
Le 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 email 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 temps 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 de branche GitHub : rulesets vs branch protection rules
GitHub propose deux façons de protéger vos branches : rulesets et branch protection rules. Comprendre la différence est important lors de la configuration des check runs GitGuardian :
Utiliser les rulesets
Si vous utilisez un ruleset et que vous exigez que les contrôles de sécurité GitGuardian passent :
- 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. S'il ne l'est pas, GitHub attendra un check run de GitGuardian qui ne sera jamais fourni, provoquant un check run perpétuellement en attente.
- Si la conclusion du check run est
Failed, GitHub affichera un avertissement spécifique. La conclusionNeutralest considérée comme un check run réussi.
Utiliser les branch protection rules
Si vous utilisez les 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, donc elles fonctionnent parfaitement avec les check runs GitGuardian sans configuration supplémentaire.
- Votre dépôt doit être activement surveillé par GitGuardian.
S'il ne l'est pas, GitHub attendra un check run de GitGuardian qui ne sera jamais fourni, provoquant un check run perpétuellement en attente.
- Si la conclusion du check run est
Failed, GitHub affichera un avertissement spécifique.
La conclusionNeutralest considérée comme 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 :
- Dépôt forké : votre copie personnelle du dépôt upstream, marqué comme
fork = truesur GitHub. - Dépôt upstream : le dépôt original.
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 rate limiting.
Ce problème survient parce que 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 des niveaux d'activité élevés. Ces pull requests automatisées sont gourmandes en ressources et peuvent entraîner des erreurs de rate limiting pendant les check runs GitGuardian.
Cependant, les managers de workspaces sous le 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'action "Skip" habituels. Dans ce scénario, GitGuardian fournit un simple bouton Skip pour éviter de bloquer le développeur.
Support de GitHub Merge Queue
Lorsqu'une pull request est ajoutée à une merge queue GitHub, GitGuardian répond avec un check run neutre car :
- L'analyse de secrets est déjà effectuée sur les pull requests avant qu'elles n'entrent dans la merge queue
- La merge queue ne crée pas de nouveaux commits qui pourraient introduire de nouveaux secrets
- Les PRs 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.
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 outrepasser la configuration définie sur le dashboard GitGuardian.
Utiliser les 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
FailedouNeutrallorsque 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 s'assurer que la fonctionnalité fonctionne correctement.
Outrepasser la présence des check runs
Types de propriétés supportés : (Text, Single select, True/False)
| Configuration globale GitGuardian | Custom property gitguardian-check-runs-enabled | ||
|---|---|---|---|
true | false | null | |
| 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 ✅ |
| 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 🚫 |
Outrepasser la conclusion des check runs
Types de propriétés supportés : (Text, Single select)
| Configuration globale GitGuardian | Custom property gitguardian-check-runs-secrets-conclusion | ||
|---|---|---|---|
neutral | failed | null ou autre | |
| Conclusion check runs si secrets est Neutral ⬛ | la conclusion check runs si secrets sera Neutral ⬛ | la conclusion check runs si secrets sera Failed ❌ (bloquant la PR) | la conclusion check runs si secrets sera Neutral ⬛ |
| Conclusion check runs si secrets est Failure ❌ | la conclusion check runs si secrets sera Neutral ⬛ | la conclusion check runs si secrets sera Failed ❌ (bloquant la PR) | la conclusion check runs si secrets sera Failed ❌ (bloquant la PR) |
Outrepasser la présence des actions skip des check runs lorsque la conclusion est Failed
Types de propriétés supportés : (Text, Single select, True/False)
| Configuration globale GitGuardian | Custom property gitguardian-check-runs-actions-enabled | ||
|---|---|---|---|
true | false | null | |
| 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 ✅ |
| 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 🚫 |
Utiliser les labels GitHub pour GitHub Enterprise Server < 3.13
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 prendre contact avec 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
FailedouNeutrallorsque 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.
Outrepasser la présence des check runs
| Configuration globale GitGuardian | Labels de dépôt GitHub Enterprise Server | |||
|---|---|---|---|---|
gitguardian:check-runs-enabled | gitguardian:check-runs-disabled | Aucun label | Les deux labels présents | |
| 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 ✅ |
| 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 ✅ |
Outrepasser la conclusion des check runs
| Configuration globale GitGuardian | Labels de 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 check runs si secrets est Neutral ⬛ | la conclusion check runs si secrets sera Neutral ⬛ | la conclusion check runs si secrets sera Failed ❌ (bloquant la PR) | la conclusion check runs si secrets sera Neutral ⬛ | la conclusion check runs si secrets sera Neutral ⬛ |
| Conclusion check runs si secrets est Failure ❌ | la conclusion check runs si secrets sera Neutral ⬛ | la conclusion check runs si secret sera Failed ❌ (bloquant la PR) | la conclusion check runs si secret sera Failed ❌ (bloquant la PR) | la conclusion check runs si secrets sera Neutral ⬛ |
Outrepasser la présence des actions skip des check runs lorsque la conclusion est Failed
| Configuration globale GitGuardian | Labels de dépôt GitHub Enterprise Server | |||
|---|---|---|---|---|
gitguardian:check-runs-actions-enabled | gitguardian:check-runs-actions-disabled | Aucun label | Les deux labels présents | |
| 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 ✅ |
| 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 ✅ |
