Intégrer GitLab

Protégez votre code source en surveillant les dépôts GitLab à la recherche de secrets exposés dans les commits, merge requests et 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 l'ensemble des environnements de développement et de production.

Capacités

Fonctionnalité	Support	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 organisations 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érifie si les secrets sont toujours accessibles
Pièces jointes	❌ (Non pris en charge)	Non applicable aux 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

Configuration

Prérequis :

• Compte Owner ou Manager sur votre Dashboard GitGuardian
• Permissions GitLab admin (pour les system hooks) ou permissions group owner (pour les group hooks)
• Personal access token avec les portées appropriées

• 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 consulter la documentation GitLab pour plus d'informations sur les system hooks et les group hooks.

Créer un Personal Access Token

Nous 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 GitLab
2. Allez dans la section Access Tokens
3. Créez un personal access token avec un nom simple tel que "GitGuardian" et la portée api.
   Le personal token permet à GitGuardian de créer des webhooks via vos permissions GitLab.

Veuillez consulter la documentation GitLab pour plus d'informations sur les personal access tokens.

info

Il est également possible d'utiliser un personal access token avec la portée 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'API Admin). Une fois cela fait, votre intégration GitLab sera fonctionnelle.

Si le « Admin mode » est activé sur votre instance GitLab, vous aurez besoin de la portée admin_mode en plus de la portée 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 par system hook n'est disponible que pour la version on-premise de GitLab (une telle intégration n'est pas possible sur GitLab.com).

astuce

Nous 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 des system hooks.

Directives

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 :
   

Détails de souscription aux événements

Notre system hook souscrira 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é du côté GitLab ou si le Personal access token devient invalide (en expirant ou en étant révoqué). Nous vous enverrons un e-mail pour vous en informer. 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 par programmation.
  
• Si le token est invalide, vous pouvez définir un nouveau personal access token en l'éditant :
  
• 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 approprié pour 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 GitLab, sous peine de rompre l'intégration.

Intégrer vos groupes GitLab avec des group hooks

Les group hooks requièrent 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 par group hook 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 par group hook.

astuce

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

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

Prérequis

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

Directives

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 alors amené sur 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 voir surveillés par GitGuardian.
   

info

Si le token a la portée read_api, une URL de hook et un secret token seront affichés une fois que vous aurez installé un nouveau groupe. Utilisez cette URL de hook et ce secret token pour ajouter un nouveau group hook (ou avec l'API Group). 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 entre eux 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 souscription aux événements

Nos group hooks souscriront 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 par 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 cas, 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 projet GitLab nouvellement créé 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 plus aucune alerte relative à ce projet.
• Le webhook installé sur ce projet existera toujours, vous pourrez donc facilement réactiver la surveillance à tout moment.