Intégrer GitHub
Protégez votre code source en surveillant les dépôts GitHub à la recherche de secrets exposés dans les commits, les branches et les pull requests.
Pourquoi surveiller GitHub ?
Les développeurs committent fréquemment des clés d'API, des identifiants de base de données et des tokens privés directement dans les dépôts GitHub. Ces secrets codés en dur deviennent accessibles à toute personne ayant accès au dépôt et restent stockés de manière permanente dans l'historique git, créant des vulnérabilités de sécurité durables qui peuvent compromettre l'ensemble de votre infrastructure.
Capacités
| Fonctionnalité | Prise en charge | Détails |
|---|---|---|
| Scan historique | ✅ (Pris en charge) | Analyse complète de l'historique du dépôt |
| Détection en temps réel | ✅ (Pris en charge) | Détection instantanée via webhooks |
| Périmètre surveillé | ✅ (Pris en charge) | Surveillance granulaire de vos Orgs et dépôts |
| Périmètre d'équipe | ✅ (Pris en charge) | Contrôle d'accès basé sur les équipes |
| Vérification de présence | ✅ (Pris en charge) | Vérifiez si les secrets sont toujours accessibles |
| Pièces jointes | ❌ (Non pris en charge) | Non applicable pour les dépôts de code |
Ce que nous scannons :
- Fichiers de code source, fichiers de configuration et fichiers texte bruts
- Toutes les branches du dépôt et l'historique des commits
Configurer votre intégration GitHub
Prérequis :
- Compte Owner ou Manager sur votre Dashboard GitGuardian
- Permissions d'administrateur d'organisation GitHub ou de propriétaire de dépôt
GitGuardian s'intègre nativement avec GitHub via une GitHub app que vous pouvez installer sur vos dépôts GitHub personnels et sur les dépôts de vos organisations GitHub. Vous pouvez consulter la documentation GitHub pour plus d'informations sur les GitHub apps.
Scanner les incidents avec la GitGuardian GitHub app
La GitGuardian GitHub app a uniquement un accès en lecture à votre code.
Facultativement, il est possible d'accorder à GitGuardian un accès en écriture pour bénéficier de fonctionnalités métier spécifiques. Consultez la section dédiée pour plus de détails.
Vous aurez besoin des droits Owner ou Manager dans GitGuardian pour configurer une intégration ou personnaliser vos paramètres.
Vous pouvez installer GitGuardian sur :
- votre compte GitHub personnel pour surveiller vos dépôts personnels,
- une organisation GitHub que vous possédez.
- Naviguez vers Settings > Integrations > Sources.
- Cliquez sur Install pour GitHub.
- Cliquez sur Install pour démarrer le processus d'installation de la GitHub app (vous serez alors redirigé vers GitHub).
- Authentifiez-vous sur GitHub si vous n'êtes pas déjà connecté.
- Choisissez où installer la GitHub app (soit pour votre compte GitHub personnel, soit pour l'organisation GitHub dont vous êtes administrateur)
- Choisissez votre mode d'installation préféré : All repositories ou Only select repositories.
- All repositories : GitGuardian sera installé sur tous les dépôts existants.
Les nouveaux dépôts seront intégrés à GitGuardian automatiquement.
- Only select repositories : GitGuardian sera uniquement installé sur les dépôts que vous sélectionnez.
Les nouveaux dépôts ne seront pas automatiquement intégrés à GitGuardian - le processus d'installation devra être relancé afin d'intégrer les nouveaux dépôts.
Nous recommandons de choisir All repositories car vous pouvez ensuite les désélectionner manuellement via le dashboard GitGuardian.
- All repositories : GitGuardian sera installé sur tous les dépôts existants.
Les nouveaux dépôts seront intégrés à GitGuardian automatiquement.
- Suivez les instructions et les dépôts GitHub que vous avez choisis seront ajoutés à votre workspace.
Si vous tentez d'installer GitGuardian sur une organisation GitHub dont vous êtes seulement membre, et non propriétaire, GitHub vous invitera à utiliser un flux « Request installation ».
Nous vous recommandons vivement d'inviter le propriétaire dans votre workspace GitGuardian pour effectuer l'intégration, rattachant ainsi l'organisation GitHub à votre workspace.
Si vous utilisez GitHub Enterprise Cloud, vous pouvez automatiser les installations de la GitHub App dans toute votre entreprise depuis un script, sans session dashboard par organisation.
Accorder des permissions d'écriture sur le code avec la GitGuardian:write GitHub app
Certaines fonctionnalités métier nécessitent des permissions d'écriture sur vos dépôts afin d'ouvrir des pull requests.
Actuellement, cela concerne la fonctionnalité Honeytoken Deployment jobs.
L'octroi de permissions d'écriture à GitGuardian se fait via l'installation d'une seconde GitHub app « GitGuardian:write ».
- Naviguez vers la section des paramètres GitHub où votre intégration est déjà configurée avec l'app principale.
- Cliquez sur Manage sources > Configure write permissions.
- Choisissez sur quelle organisation vous souhaitez installer la GitHub app, puis choisissez votre mode d'installation préféré (toute l'organisation ou les dépôts sélectionnés). Notez que vous devez l'installer sur les dépôts où la GitHub principale est déjà installée si vous voulez les voir dans le dashboard GitGuardian.
Intégration avec GitGuardian Self-Hosted
Nous recommandons d'utiliser des workers dédiés pour cette intégration. Pour des informations plus détaillées sur le scaling et la configuration, veuillez visiter notre page scaling.
Si vous utilisez une instance GitGuardian Self-Hosted, vous devez d'abord créer une GitHub App dédiée afin de posséder l'ensemble du flux de données. GitGuardian s'en charge pour vous de manière programmatique via le manifeste GitHub. Cela garantira que votre GitHub App est créée avec tous les droits appropriés.
Par défaut, la GitGuardian GitHub app a uniquement un accès en lecture à votre code.
Facultativement, il est possible d'accorder à GitGuardian un accès en écriture pour bénéficier de fonctionnalités métier spécifiques (plus de détails dans cette section dédiée).
Vous aurez besoin des droits Owner ou Manager dans GitGuardian pour configurer une intégration ou personnaliser vos paramètres.
- Naviguez vers Settings > Integrations > Sources.
- Cliquez sur Configure pour GitHub.
- Cliquez sur Install pour démarrer le processus de création et d'installation de la GitHub app.
- Choisissez un nom et validez la création de la GitHub App.
- Une fois la GitHub app créée, vous pouvez désormais suivre les étapes d'installation SAAS à partir de l'étape 5 ci-dessus et choisir les organisations GitHub à intégrer à GitGuardian.
La GitHub App appartient à l'utilisateur qui l'a créée. Nous vous recommandons de transférer la propriété à une organisation au cas où l'utilisateur serait ultérieurement désactivé.
IMPORTANT : GitGuardian ne peut pas surveiller les dépôts dont le propriétaire n'a pas installé la GitHub App. Si le dépôt appartient à une organisation GitHub, le propriétaire de l'organisation doit installer la GitHub App.
Accorder à GitGuardian des permissions d'écriture sur le code
Certaines fonctionnalités métier nécessitent des permissions d'écriture sur vos dépôts afin d'ouvrir des pull requests.
Actuellement, cela concerne la fonctionnalité Honeytoken Deployment jobs.
Pour permettre à GitGuardian d'ouvrir des pull requests sur les dépôts de votre instance, accédez à la page des paramètres de l'app dans GitHub, dans l'onglet « Permissions & events ». Dans la section « Repository permissions », changez les permissions sur Contents en « Read and write » :
Ce changement doit ensuite être propagé aux organisations où cette app est installée, en acceptant la demande de mise à jour des permissions :
Ajouter de nouveaux dépôts
Vous pouvez ajouter de nouvelles organisations ou de nouveaux dépôts en cliquant sur add another sur la page de la liste des intégrations ou sur la page d'intégration GitHub.
Vous pouvez également reconfigurer un compte GitHub personnel / une organisation GitHub précédemment installé et changer le mode d'installation en All repositories ou Only select repositories.
Scan historique automatique
Par défaut, GitGuardian effectue un scan historique pour chaque nouveau dépôt GitHub créé et ajouté à votre périmètre.
Vous pouvez désactiver ce comportement dans vos paramètres GitHub si vous êtes Manager du workspace.
Surveillance automatique des dépôts
Par défaut, GitGuardian surveille automatiquement les dépôts ajoutés à votre périmètre.
Vous pouvez désactiver ce comportement dans vos paramètres GitHub si vous êtes Manager du workspace.
Comprendre les capacités de scan
Scan historique
Découvrez votre dette de secrets : Lors de votre première intégration de cette source, GitGuardian effectue un scan complet de l'intégralité de votre historique de contenu, en fonction de votre périmètre personnalisé. Cela révèle des secrets qui ont pu être exposés il y a des semaines, des mois, voire des années — vous aidant à traiter votre dette de sécurité existante.
Comment déclencher un scan historique : Rendez-vous sur votre page de périmètre, sélectionnez les sources que vous souhaitez scanner, puis cliquez sur Scan dans la barre d'actions groupées. Consultez Gérer votre périmètre surveillé pour connaître les limites de taille selon le plan, la gestion des erreurs et tous les détails.
Scan en temps réel
Détectez instantanément les nouvelles expositions : Une fois intégré, GitGuardian surveille en continu votre contenu grâce à une détection basée sur les événements. Tout contenu nouveau ou modifié contenant des secrets est détecté immédiatement, vous permettant de réagir rapidement aux nouvelles expositions.
Personnaliser votre périmètre surveillé
Une fois votre intégration GitHub configurée, vous pouvez configurer quels dépôts surveiller dans la section des paramètres GitHub de votre workspace.
Si vous désélectionnez un dépôt de votre périmètre surveillé :
- GitGuardian ne récupérera plus le contenu de ses commits, et par conséquent aucune alerte ne sera déclenchée pour ce dépôt.
- La GitGuardian GitHub app restera installée sur ce dépôt, vous pouvez donc facilement réactiver la surveillance.
Gérer votre intégration
Surveillance de la santé et maintenance
Si vous devez modifier les paramètres de votre intégration ou résoudre des problèmes de connectivité, accédez à l'interface de gestion via Sources integration.
Désinstaller l'intégration
Bien que notre objectif soit de vous aider à maintenir une couverture de sécurité complète, vous pouvez désinstaller l'intégration chaque fois que nécessaire :
- Naviguez vers Sources integration
- Cliquez sur Edit à côté du nom de l'intégration
- Cliquez sur Configure
- Cliquez sur l'icône delete à côté de votre ressource
- Confirmez la suppression
Note : la suppression de l'intégration préserve votre historique d'incidents, mais arrête les analyses futures et les vérifications de présence pour les intégrations qui le supportent.
