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écuteront côté serveur sur le VCS, à l'étape post-receive.

Les scans de secrets GitGuardian s'exécutent sur chaque commit individuel qui compose la pull request, et pas uniquement sur l'état final du code dans la pull request. Ce scan approfondi permet de 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. 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 la possibilité d'une remédiation plus facile. Le résultat : des branches collaboratives sans secrets, telles que celles utilisées pour les environnements de QA, staging et production.

À quoi cela ressemble

Dans l'interface GitHub, un check run GitGuardian présente un tableau avec toutes les détections 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 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.).

Checkruns conclusion in GitHub UI

Checkruns details in GitHub UI

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.

Incidents details with pull request links

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, afin que vous puissiez auditer la couverture de scan et dépanner les runs en échec sans quitter GitGuardian. Vous la trouverez sous Perimeter > Internal monitoring > GitHub check runs.

GitHub check runs dashboard

En haut de la page, trois indicateurs résument votre activité de check runs :

Check run mode : votre paramètre de conclusion actuel lorsque des secrets sont détectés (blocking ou neutral).
Pull requests with secrets : la part des pull requests scannées où des secrets ont été trouvés au cours des 7 derniers jours.
Success rate : la part des 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 du dernier run et sa durée.

Utilisez la barre de filtres pour affiner la liste par dépôt, statut ou date, ou pour rechercher un commit ou une pull request spécifique. Deux valeurs de statut méritent une attention particulière :

Failed, affiché comme Blocking : le check run a trouvé des secrets et sa conclusion est définie sur Failed, la pull request est donc 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 skip actions 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 signalés par un check run pour commencer la remédiation.

Chaque ligne propose également des actions afin de débloquer les développeurs sans passer à GitHub :

Re-run un check run, par exemple après avoir remédié aux secrets détectés ou lorsqu'un run s'est terminé en erreur.
Skip un check run lorsqu'il ne doit 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 page de paramètres GitHub Enterprise Server.

GitHub Check Runs

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

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, en particulier si vous activez GitGuardian pour publier un commentaire afin d'améliorer la visibilité des secrets détectés dans la pull request. Consultez la section ci-dessous pour plus d'informations.

Checkruns status setting

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 provenant de 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 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 skip actions

Lorsque la conclusion des checkruns si des secrets sont détectés 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 skip actions reflètent les raisons d'ignorance disponibles sur le dashboard, étant entendu qu'ignorer un checkrun contenant un secret équivaut à ignorer l'incident associé. Les skip actions disponibles incluent :

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

GitHub checkruns skip buttons

Lorsqu'une skip action 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

Skip actions tags

En tant que manager du workspace, vous avez la possibilité de désactiver entièrement la possibilité 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 de checkrun et s'assurer que vos développeurs ne les manquent pas, GitGuardian publie un commentaire lorsqu'un secret est détecté.

Pull request comment

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.

Customize remediation guidelines

Lorsque cette option 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 l'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 durées 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 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 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 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.

rulesets

Utilisation des branch protection rules

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

Branch protection rule

Les branch protection rules ne s'appliquent qu'aux pull requests, et non aux pushes directs sur la branche, elles fonctionnent donc 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 :

Dépôt forké : Votre copie personnelle du dépôt upstream, marquée comme fork = true sur GitHub.
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 pour é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 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 habituels boutons d'actions "Skip". Dans ce scénario, GitGuardian fournit un simple bouton Skip pour éviter de bloquer le développeur.

Forked repositories PR

Support de la GitHub Merge Queue

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

Le scan de secrets est déjà effectué sur les pull requests avant leur entrée dans la merge queue
La merge queue ne crée pas de nouveaux commits susceptibles d'introduire de nouveaux secrets
Les PR doivent réussir 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.

Très grandes pull requests

Comme un check run scanne chaque commit d'une pull request via l'API GitHub, les très grandes pull requests peuvent générer un volume élevé d'appels API. L'installation de la GitHub App a une limite de débit partagée de 5 000 requêtes par heure pour toute votre organisation (voir les rate limits 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 le rate limit 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, les développeurs ne voient donc aucune différence, bien que cela puisse prendre légèrement plus de temps à 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 de 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 outrepasser 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 en Failed ou Neutral lorsque des secrets sont détectés.
si les skip actions sont disponibles ou non.

custom properties to override check run settings

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

Outrepasser la présence des check runs

Types de propriété 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 🚫

Outrepasser la conclusion des check runs

Types de propriété 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 si secrets est Neutral ⬛	la conclusion des check runs si secrets sera Neutral ⬛	la conclusion des check runs si secrets sera Failed ❌ (bloquant la PR)	la conclusion des check runs si secrets sera Neutral ⬛
La conclusion des check runs si secrets est Failure ❌	la conclusion des check runs si secrets sera Neutral ⬛	la conclusion des check runs si secrets sera Failed ❌ (bloquant la PR)	la conclusion des check runs si secrets sera Failed ❌ (bloquant la PR)

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

Types de propriété 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 🚫

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 en Failed ou Neutral lorsque des secrets sont détectés.
si les skip actions sont disponibles ou non.

Repo label to override check run settings

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