Intégrer GitLab

Protégez votre code source en surveillant les dépôts GitLab à la recherche de secrets exposés dans les commits, les merge requests et les fichiers de projet.

Pourquoi surveiller GitLab ?

Les dépôts GitLab constituent l'épine dorsale des workflows DevOps modernes, ce qui en fait des cibles privilégiées pour l'exposition de secrets. Lorsque les développeurs committent des identifiants, des tokens d'API ou des secrets de configuration, ils créent des vulnérabilités permanentes dans l'historique git qui peuvent être exploitées par quiconque obtient l'accès au dépôt, compromettant potentiellement des environnements de développement et de production entiers.

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

• Les fichiers de code source, les fichiers de configuration et les fichiers de texte brut
• Toutes les branches du dépôt et l'historique des commits

Configuration

Prérequis :

• Un compte Owner ou Manager sur votre Dashboard GitGuardian
• Pour l'intégration avec system hooks : des permissions GitLab admin, ou un token non-admin
• Pour l'intégration avec group hooks : des permissions group owner
• Un personal access token avec les scopes appropriés

• Connectivité réseau entre GitGuardian et vos services self-hosted. Découvrez GitGuardian Bridge pour permettre des connexions sécurisées entre GitGuardian SaaS et vos services self-hosted dans des réseaux privés.

Limites de débit

Si votre instance applique des limites de débit API, les valeurs par défaut peuvent être trop basses et ralentir le scan de GitGuardian. Pour scanner dans un délai raisonnable, augmentez les limites ou exemptez de la limitation de débit le compte, le token ou le compte de service utilisé par GitGuardian. Voir Limites de débit sur les sources self-hosted.

GitGuardian s'intègre à GitLab de deux manières : au niveau de l'instance avec des system hooks ou au niveau du groupe avec des group hooks. Veuillez vous référer à la documentation GitLab pour plus d'informations sur les system hooks et les group hooks.

Créer un personal access token

Nous vous recommandons fortement d'utiliser un utilisateur bot afin de générer des personal access tokens.

attention

Comme mentionné ci-dessus, seuls les personal access tokens sont actuellement pris en charge. Les autres types de tokens (comme les group access tokens) ne sont pas pris en charge.

1. Naviguez vers les paramètres utilisateur de votre GitLab
2. Allez dans la section Access Tokens
3. Créez un personal access token avec un nom simple tel que « GitGuardian » et le scope api.
   Le personal token permet à GitGuardian de créer des webhooks grâce à vos permissions GitLab.

Veuillez vous référer à la documentation GitLab pour plus d'informations sur les personal access tokens.

info

Il est également possible d'utiliser un personal access token avec le scope read_api. Dans ce cas, une URL de hook et un secret token seront affichés une fois le formulaire soumis. Utilisez cette URL de hook et ce secret token pour ajouter un nouveau system hook sur votre instance GitLab (ou avec l'Admin API). Une fois cela fait, votre intégration GitLab sera fonctionnelle.

Si le « Admin mode » est activé sur votre instance GitLab, vous aurez besoin du scope admin_mode en plus du scope api ou read_api.

Intégrer votre instance GitLab avec des system hooks

Les system hooks ne peuvent être créés que par un administrateur de l'instance, ils donnent accès aux projets appartenant à tous les utilisateurs et groupes. L'intégration avec system hooks n'est disponible que pour la version on-premise de GitLab (une telle intégration n'est pas possible sur GitLab.com).

astuce

Nous vous recommandons d'utiliser un utilisateur bot lors de l'intégration avec GitGuardian.

Prérequis

• GitLab auto-géré : GitLab Community Edition ou tout plan de GitLab Enterprise Edition. v11.0+
• GitLab.com (SaaS) : IMPORTANT GitGuardian ne peut pas s'intégrer à GitLab.com (SaaS) via les System hooks.

Consignes

1. Naviguez vers Settings > Integrations > Sources.
2. Cliquez sur Configure pour GitLab.
3. Cliquez sur Start pour l'option system hook : « Monitor the entire GitLab instance »
4. Soumettez l'URL de votre instance GitLab et le personal access token créé.
   
   attention

   L'URL de l'instance GitLab doit être préfixée par https://, les instances sans connexion sécurisée ne seront pas surveillées.

5. GitGuardian commencera instantanément à surveiller votre instance GitLab. Vous pouvez voir les projets et groupes surveillés dans votre page de paramètres GitLab en cliquant sur See my GitLab perimeter :
   

Surveiller une instance avec un token non-admin (intégration avec system hooks)

L'intégration avec system hooks utilisant un token non-admin n'est pas activée par défaut. Si votre politique de sécurité interdit un token admin, contactez le support GitGuardian pour activer cette option pour votre workspace.

Dans ce mode, le token utilisé par GitGuardian est un token utilisateur ordinaire, auquel l'accès est accordé projet par projet. Le system hook lui-même sera créé manuellement par un administrateur de l'instance :

1. Créez le personal access token sur un utilisateur bot avec le scope read_api.
2. Donnez à cet utilisateur au moins le rôle Reporter sur chaque projet ou groupe à surveiller. L'appartenance à un groupe couvre également ses sous-groupes.
3. Soumettez l'URL de votre instance GitLab et ce token dans le formulaire de system hook, puis utilisez l'URL de hook et le secret token affichés pour créer le system hook sur votre instance.

GitGuardian rafraîchit le périmètre toutes les trois heures et surveille chaque projet que le token peut lire : les projets dans les groupes auxquels l'utilisateur appartient et dans leurs sous-groupes, les projets dans un groupe que l'utilisateur atteint uniquement via une appartenance à un projet, et les projets dans un namespace personnel.

remarque

GitLab n'accepte aucun membre sur un namespace personnel, donnez donc à l'utilisateur l'accès au projet personnel lui-même. GitGuardian le surveille alors comme n'importe quel autre projet.

Détails de l'abonnement aux événements

Notre system hook s'abonnera aux événements suivants :

• Repository update events
• Push events
• Merge request events

et la vérification SSL sera activée.

Dépannage

• GitGuardian détecte automatiquement si le system hook est supprimé côté GitLab ou si le personal access token devient invalide (par expiration ou révocation). Nous vous enverrons un e-mail pour vous notifier. Toutes vos données existantes resteront accessibles.
• Si votre instance GitLab est marquée comme « non surveillée » mais que le personal access token associé est toujours actif, vous pouvez la réactiver en cliquant sur le bouton synchronize. Cela recréera un system hook de manière programmatique.
  
• Si le token est invalide, vous pouvez définir un nouveau personal access token en le modifiant :
  
• Si le token admin est révoqué, GitGuardian le détectera et désactivera automatiquement votre intégration GitLab si aucun autre token actif n'est présent. Si un autre token adapté à la surveillance existe, l'intégration GitLab utilisera ce token. Toutes vos données existantes resteront accessibles.

attention

IMPORTANT : Ne modifiez pas l'URL ou le personal access token du system hook depuis l'interface admin de GitLab, car cela romprait l'intégration.

Intégrer vos groupes GitLab avec des group hooks

Les group hooks nécessitent que l'utilisateur ait le rôle Owner sur les groupes GitLab à surveiller. Les group hooks ne prennent pas en charge la surveillance des projets personnels des utilisateurs GitLab. L'intégration avec group hooks fonctionne à la fois pour GitLab on-premise et GitLab.com. Notez que vous ne pouvez surveiller que jusqu'à 50 000 projets par groupe pour une intégration avec group hooks.

astuce

Nous vous recommandons d'utiliser un utilisateur bot lors de l'intégration avec GitGuardian.

Notez que vous ne pouvez pas avoir une intégration avec system hooks et une intégration avec group hooks en même temps.

Prérequis

• GitLab auto-géré : plan Starter et niveaux supérieurs. v13.5+
• GitLab.com (SaaS) : plan Premium

Consignes

1. Naviguez vers Settings > Integrations > Sources.
2. Cliquez sur Configure pour GitLab.
3. Cliquez sur Start pour l'option group hook : « Monitor only certain GitLab groups »
4. Soumettez l'URL de votre instance GitLab et le personal access token, et veillez à nommer ce personal access token car vous pourriez en utiliser plusieurs à l'avenir pour intégrer davantage de groupes GitLab.
   
   attention

   L'URL de l'instance GitLab doit être préfixée par https://, les instances sans connexion sécurisée ne seront pas surveillées.

5. Vous êtes ensuite redirigé vers la page de configuration de votre intégration GitLab où vous pouvez voir la liste de tous les groupes et sous-groupes GitLab auxquels votre personal access token donne accès.
   Cliquez sur Install pour les groupes et sous-groupes GitLab que vous souhaitez que GitGuardian surveille.
   

info

Si le token a le scope read_api, une URL de hook et un secret token seront affichés une fois que vous installez un nouveau groupe. Utilisez cette URL de hook et ce secret token pour ajouter un nouveau group hook (ou avec la Group API). Une fois cela fait, votre intégration sera fonctionnelle pour ce groupe.

6. Vous pouvez voir les projets et groupes surveillés dans votre page de paramètres GitLab
   

Remarques sur l'installation

• Lorsque vous choisissez d'installer un groupe GitLab, tous ses sous-groupes seront également installés automatiquement. Ce faisant, le groupe « parent » et les sous-groupes « enfants » sont liés ensemble et si vous souhaitez désinstaller un seul sous-groupe, vous devrez d'abord désinstaller le groupe « parent ».
• Un groupe GitLab ne peut pas appartenir à deux personal access tokens. Par conséquent, lorsque vous souhaitez installer un groupe « parent » qui a un sous-groupe déjà installé, vous devez d'abord désinstaller le sous-groupe « enfant ».

Détails de l'abonnement aux événements

Nos group hooks s'abonneront aux événements suivants :

• Repository update events
• Push events
• Merge request events

et la vérification SSL sera activée.

Dépannage

• Vous pouvez soumettre de nouveaux personal access tokens si vous souhaitez surveiller davantage de groupes GitLab. Plusieurs tokens peuvent être ajoutés pour l'intégration avec group hooks. Si plusieurs tokens sont associés au même groupe GitLab, vous devez choisir quel token le surveillera.
  
• Si le token est révoqué, le groupe ne sera plus surveillé (vous pouvez l'installer à nouveau avec un autre token, mais GitGuardian ne choisira pas arbitrairement un autre token pour vous). Dans ce scénario, vous recevrez un e-mail vous informant du statut non surveillé de l'intégration.

Scan historique automatique

Par défaut, GitGuardian effectue un scan historique pour chaque nouveau projet GitLab créé et ajouté à votre périmètre.

Vous pouvez désactiver ce comportement dans vos paramètres GitLab 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 GitLab 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 GitLab configurée, vous avez la possibilité de configurer quels projets surveiller dans la section des paramètres GitLab de votre workspace.

Si vous désélectionnez un projet de votre périmètre surveillé :

• GitGuardian ne récupérera plus le contenu de ses commits, vous ne recevrez donc aucune alerte liée à ce projet.
• Le webhook installé sur ce projet existera toujours, vous pouvez donc facilement réactiver la surveillance à tout moment.

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.