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 contexte des GitHub Check Runs s'exécutent 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 de la pull request. Ce scan approfondi permet de révéler 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 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 tous les résultats 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 secret sont fermés sur le dashboard GitGuardian, ils ne seront plus remontés par les check runs GitHub.
• le type de secret
• le sha du commit
• le nom du fichier
• et aussi 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 secret détectés lors des 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.

Surveiller vos check runs depuis le dashboard

La page GitHub check runs liste chaque check run déclenché sur vos dépôts surveillés, vous permettant d'auditer la couverture des scans et de dépanner les exécutions échouées sans quitter GitGuardian. Vous la trouverez sous Perimeter > Internal monitoring > GitHub check runs.

En haut de la page, trois indicateurs résument l'activité de vos check runs :

• Check run mode : votre paramètre de conclusion actuel lorsque des secrets sont détectés (bloquant ou neutre).
• Pull requests with secrets : la proportion de pull requests scannées où des secrets ont été trouvés au cours des 7 derniers jours.
• Success rate : la proportion de check runs qui se sont terminés sans trouver de secrets au cours des 7 derniers jours.

Parcourir et filtrer les check runs

Des onglets rapides répartissent les check runs par résultat : Secrets found, Errors, Running et No secrets found. Chaque check run affiche son dépôt source, son statut, le SHA du commit, les pull requests associées, les incidents liés, la date de dernière exécution et la durée.

Utilisez la barre de filtres pour affiner la liste par dépôt, statut ou date, ou recherchez un commit ou une pull request spécifique. Deux valeurs de statut méritent un examen plus attentif :

• Failed, affiché comme Blocking : le check run a trouvé des secrets et sa conclusion est définie sur Failed, de sorte que la pull request est bloquée jusqu'à ce que les secrets soient remédiés ou que le check run soit ignoré.
• Skipped : un développeur a utilisé l'une des actions de skip sur le check run dans GitHub, ou le check run a expiré avant de se terminer et a été ignoré automatiquement pour éviter de bloquer la pull request.

Agir sur un check run

Depuis la colonne Incidents, accédez directement aux incidents de secret remontés par un check run pour commencer la remédiation.

Chaque ligne propose également des actions pour vous permettre de débloquer les développeurs sans passer par GitHub :

• Re-run un check run, par exemple après avoir remédié aux secrets détectés ou lorsqu'une exécution s'est terminée en erreur.
• Skip un check run lorsqu'il ne devrait pas bloquer la pull request.

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 (On) ou de désactiver (Off) 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 GitHub check runs 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'atteignent pas la production.
  Pour éviter des blocages complets, GitGuardian fournit des boutons d'action de 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 qu'il poste un commentaire afin d'améliorer la visibilité des secrets détectés dans la pull request. Reportez-vous à la section ci-dessous pour plus d'informations.

Ignorer les commits de merge dans les check runs de pull request

Par défaut, les check runs scannent chaque commit qui compose une pull request, y compris les commits de merge qui intègrent des changements 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 des commits créés sur la branche de la PR.

Activer ou désactiver les actions de skip

Lorsque la conclusion des check runs 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 de skip pour éviter d'entraver complètement les développeurs.
Ces actions de skip reflètent les raisons d'ignorer disponibles sur le dashboard, étant entendu qu'ignorer (skip) un check run contenant un secret revient à ignorer l'incident associé. Les actions de skip disponibles incluent :

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

Lorsqu'une action de 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 check run 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é à ignorer les check runs dans vos paramètres.

Poster un commentaire dans la timeline de la pull request

Pour étendre la visibilité des résultats des check runs et vous assurer que vos développeurs ne les manquent pas, GitGuardian poste 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.

Synchroniser les commentaires de pull request avec les notes d'incident

Les développeurs peuvent expliquer un secret détecté sans quitter GitHub : un faux positif, un identifiant de test ou une référence de ticket. Lorsqu'ils commentent la pull request et mentionnent @gitguardian, GitGuardian ajoute le commentaire en tant que note à chaque incident trouvé par les check runs de cette pull request. La note renvoie au commentaire GitHub et affiche son auteur, afin que les équipes de sécurité puissent lire le contexte dans le dashboard ou via l'API. Les notes sont limitées à 10 000 caractères ; le lien donne accès au commentaire complet.

Cette option est désactivée par défaut. Les Managers du workspace peuvent l'activer dans vos paramètres, séparément pour GitHub et GitHub Enterprise. Une fois activée, le résumé du check run invite les développeurs à commenter. Les commentaires sans la mention @gitguardian et les commentaires postés par des bots sont ignorés. Sur les dépôts publics, seuls les commentaires du propriétaire du dépôt, des membres et des collaborateurs sont synchronisés.

Personnaliser les consignes de remédiation

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

Utiliser des liens de partage publics pour les détails d'incident

Lorsqu'elle est activée, les check runs génèrent automatiquement des liens de partage publics qui permettent aux développeurs d'accéder aux détails d'incident 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 de concert 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 une personne 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 d'auto-partage.

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 : les rulesets et les 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 exigez que les contrôles de sécurité GitGuardian réussissent :

• 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 push 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 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.

Utiliser les 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 s'appliquent uniquement aux pull requests, pas aux push directs sur la branche, de sorte qu'elles fonctionnent de manière transparente 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 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 (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 limitation de débit lors des check runs GitGuardian.

Cependant, les managers des 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.

Prise en charge de GitHub Merge Queue

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

• Le scan de 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 qui pourraient 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 contrôle GitGuardian est marqué comme requis.

Pull requests très volumineuses

Comme 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 de la GitHub App dispose d'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.

Une pull request est considérée comme surdimensionnée lorsqu'elle dépasse l'une de ces limites :

• plus de 200 commits (la propre limite de check run de GitHub est de 250)
• plus de 60 000 fichiers modifiés
• plus de 300 000 lignes modifiées

Plan Business : au lieu d'atteindre l'API GitHub commit par commit, GitGuardian scanne les pull requests surdimensionnées en clonant la branche du dépôt et en la scannant localement, la même approche basée sur le clonage utilisée pour les scans historiques. Cela évite de consommer la limite de débit de l'API GitHub de votre organisation tout en scannant l'intégralité de la pull request. Le check run rapporte le même résultat et les mêmes annotations qu'un check run standard, de sorte que les développeurs ne voient aucune différence, bien qu'il puisse prendre un peu plus de temps à se terminer.

Autres plans : pour protéger le budget API de votre organisation, GitGuardian ignore le scan du check run sur les pull requests dépassant les limites de taille. Le skip s'applique uniquement aux pull requests dépassant les limites, il est donc peu fréquent, et le résultat est visible sous forme de 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.

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 :

• la présence ou non du check run
• la spécification de la conclusion comme Failed ou Neutral lorsque des secrets sont détectés.
• la disponibilité ou non des actions de skip.

Il est crucial d'utiliser les noms exacts des custom properties donné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
La conclusion des check runs en cas de secrets est Neutral ⬛	la conclusion des check runs en cas de secrets sera Neutral ⬛	la conclusion des check runs en cas de secrets sera Failed ❌ (bloquant la PR)	la conclusion des check runs en cas de secrets sera Neutral ⬛
La conclusion des check runs en cas de secrets est Failure ❌	la conclusion des check runs en cas de secrets sera Neutral ⬛	la conclusion des check runs en cas de secrets sera Failed ❌ (bloquant la PR)	la conclusion des check runs en cas de secrets sera Failed ❌ (bloquant la PR)

Remplacer la présence des actions de 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 de skip sont activés ✅	les boutons d'action de skip seront présents ✅	les boutons d'action de skip ne seront pas présents 🚫	les boutons d'action de skip seront présents ✅
Les boutons d'action de skip sont désactivés 🚫	les boutons d'action de skip seront présents ✅	les boutons d'action de skip ne seront pas présents 🚫	les boutons d'action de skip ne seront pas présents 🚫

Utiliser les 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 :

• la présence ou non du check run.
• la spécification de la conclusion comme Failed ou Neutral lorsque des secrets sont détectés.
• la disponibilité ou non des actions de skip.

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 de 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 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
La conclusion des check runs en cas de secrets est Neutral ⬛	la conclusion des check runs en cas de secrets sera Neutral ⬛	la conclusion des check runs en cas de secrets sera Failed ❌ (bloquant la PR)	la conclusion des check runs en cas de secrets sera Neutral ⬛	la conclusion des check runs en cas de secrets sera Neutral ⬛
La conclusion des check runs en cas de secrets est Failure ❌	la conclusion des check runs en cas de secrets sera Neutral ⬛	la conclusion des check runs en cas de secret sera Failed ❌ (bloquant la PR)	la conclusion des check runs en cas de secret sera Failed ❌ (bloquant la PR)	la conclusion des check runs en cas de secrets sera Neutral ⬛

Remplacer la présence des actions de 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
Les boutons d'action de skip sont activés ✅	les boutons d'action de skip seront présents ✅	les boutons d'action de skip ne seront pas présents 🚫	les boutons d'action de skip seront présents ✅	les boutons d'action de skip seront présents ✅
Les boutons d'action de skip sont désactivés 🚫	les boutons d'action de skip seront présents ✅	les boutons d'action de skip ne seront pas présents 🚫	les boutons d'action de skip ne seront pas présents 🚫	les boutons d'action de skip seront présents ✅