Aller au contenu principal

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 façon permanente dans l'historique git, créant des vulnérabilités de sécurité durables qui peuvent compromettre l'ensemble de votre infrastructure.

Fonctionnalités​

FonctionnalitéPrise en chargeDé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érifier 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 de texte brut
  • Toutes les branches de dépôt et l'historique des commits

Configurer votre intégration GitHub​

Prérequis :

  • Compte Owner ou Manager sur votre Dashboard GitGuardian
  • Permissions GitHub organization admin ou repository owner

GitGuardian s'intègre nativement à 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 vous référer à la documentation GitHub pour plus d'informations sur les GitHub apps.

Scanner les incidents avec la GitGuardian GitHub app​

info

La GitGuardian GitHub app dispose d'un accès en lecture seule à votre code.
En option, 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 dont vous êtes propriétaire.
  1. Naviguez vers Settings > Integrations > Sources.
  2. Cliquez sur Install pour GitHub.
  3. Cliquez sur Install pour démarrer le processus d'installation de la GitHub app (vous serez alors redirigé vers GitHub).
  4. Authentifiez-vous sur GitHub si vous n'êtes pas déjà connecté.
  5. Choisissez où installer la GitHub app (soit pour votre compte GitHub personnel, soit pour l'organisation GitHub dont vous êtes admin)
    choose actor
  6. 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 automatiquement à GitGuardian.
    • Only select repositories : GitGuardian ne sera installé que 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é pour intégrer de nouveaux dépôts.

      Nous recommandons de choisir All repositories puisque vous pouvez ensuite les désélectionner manuellement via le dashboard GitGuardian.
      choose repositories
  7. Suivez les instructions et vos dépôts GitHub choisis seront ajoutés à votre workspace.
    GitGuardian monitored perimeter
info

Si vous tentez d'installer GitGuardian sur une organisation GitHub dont vous n'êtes que 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 réaliser l'intégration, rattachant ainsi l'organisation GitHub à votre workspace.

Intégration de plusieurs organisations

Si vous utilisez GitHub Enterprise Cloud, vous pouvez automatiser les installations de la GitHub App à travers votre entreprise depuis un script, sans session du dashboard par organisation.

Accorder des permissions d'écriture sur le code avec la GitGuardian:write GitHub app​

info

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 ».

  1. Naviguez vers la section GitHub settings où votre intégration est déjà configurée avec l'app principale.
  2. Cliquez sur Manage sources > Configure write permissions. Configure write permissions via GitGuardian
  3. 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​

info

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'intégralité du flux de données. GitGuardian le gère pour vous de manière programmatique via le manifest GitHub. Cela garantira que votre GitHub App est créée avec tous les droits appropriés.

info

Par défaut, la GitGuardian GitHub app dispose d'un accès en lecture seule à votre code.

En option, 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.

  1. Naviguez vers Settings > Integrations > Sources.
  2. Cliquez sur Configure pour GitHub.
  3. Cliquez sur Install pour démarrer le processus de création et d'installation de la GitHub app.
  4. Choisissez un nom et validez la création de la GitHub App. GHE app creation via manifest
  5. 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 avec GitGuardian.
attention

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é.

Transfer GitHub app

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​

info

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 autoriser GitGuardian à ouvrir des pull requests sur les dépôts de votre instance, rendez-vous sur la page des paramètres de l'app dans GitHub, dans l'onglet « Permissions & events ». Dans la section « Repository permissions », modifiez les permissions sur Contents en « Read and write » :

Update app permissions

Ce changement doit ensuite être propagé aux organisations où cette app est installée, en acceptant la demande de mise à jour des permissions :

App permission update request

Confirm app permission update

Ajouter de nouveaux dépôts​

Vous pouvez ajouter de nouvelles organisations ou 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éé ajouté à votre périmètre.

Vous pouvez désactiver ce comportement dans vos GitHub settings si vous êtes Manager du workspace.

Autoscan settings

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 GitHub settings 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.

Synchroniser les équipes et les membres depuis GitHub​

GitGuardian peut refléter votre organisation GitHub dans votre workspace : les équipes sont créées, leurs membres sont ajoutés avec les permissions correspondantes, et chaque périmètre d'équipe est rempli avec les dépôts que l'équipe possède. La synchronisation s'exécute toutes les 24 heures.

Dans la section Team synchronization de vos GitHub settings, cliquez sur Add organization et sélectionnez l'organisation à refléter. Consultez Synchroniser les utilisateurs et les équipes pour connaître les prérequis, les options et les détails de ce qui est synchronisé.

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 GitHub settings 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 :

  1. Naviguez vers Sources integration
  2. Cliquez sur Edit à côté du nom de l'intégration
  3. Cliquez sur Configure
  4. Cliquez sur l'icône delete à côté de votre ressource
  5. 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.