Pre-receive

Préambule

Un pre-receive hook vous permet de rejeter les commits qui sont poussés vers un dépôt git s'ils ne valident pas chaque vérification. Veuillez vous référer à notre learning center pour plus d'informations.

Le hook pre-receive GitGuardian est exécuté via notre application CLI ggshield. ggshield est un wrapper autour de l'API GitGuardian pour la détection de secrets qui nécessite une clé API pour fonctionner.

Étant donné que les hooks pre-receive sont configurés pour s'exécuter de manière programmatique sur l'instance VCS, nous recommandons l'utilisation d'un compte de service dédié pour authentifier les appels ggshield. Pour créer un compte de service, connectez-vous à votre workspace GitGuardian et accédez à la section API.

Vous trouverez des exemples de hooks pre-receive ggshield dans doc/pre-receive.sample et doc/pre-receive-docker.sample.

info

GitGuardian prend en charge les hooks pre-receive sur GitHub Enterprise Server, mais GitHub impose un délai d'expiration de 5 secondes pour les évaluations de push. Si l'évaluation dépasse cette limite, le push est rejeté. Cela peut affecter la fiabilité du hook pre-receive. Pour plus de détails, consultez la documentation des hooks pre-receive de GitHub.

Aperçu

info

Personnalisez le message de remédiation et ajoutez le vôtre pour offrir aux développeurs des conseils précis pour résoudre leurs problèmes de code et continuer leur travail.

En savoir plus ici - Message de remédiation personnalisé GitGuardian CLI

GitLab Self-Managed et Bitbucket Server

Installer le hook git pre-receive ggshield

Le script d'exemple peut être trouvé dans pre-receive.sample.

1. Ce hook pre-receive nécessite que la machine hôte ait python>=3.8 et pip installés

2. Installez ggshield depuis pip : pip install ggshield

3. Déplacez pre-receive.sample vers .git/hooks/pre-receive ou vers le répertoire de hooks git de votre fournisseur

   • GitLab
   • Bitbucket Server/Datacenter

4. Marquez le script comme exécutable avec chmod +x .git/hooks/pre-receive

5. Définissez la variable d'environnement GITGUARDIAN_API_KEY. Soit dans un fichier de configuration global de la machine, soit dans le fichier .git/hooks/pre-receive, comme indiqué dans le fichier d'exemple.

Installer le hook git pre-receive ggshield avec Docker

Pour que le hook pre-receive fonctionne, le répertoire où sont stockés les dépôts doit également être monté sur le conteneur.

Le script d'exemple peut être trouvé dans pre-receive-docker.sample

Ce hook pre-receive nécessite que la machine hôte ait Docker installé.

1. Téléchargez le script en tant que .git/hooks/pre-receive :

   curl -L https://github.com/GitGuardian/ggshield/raw/main/doc/pre-receive-docker.sample > .git/hooks/pre-receive

2. Rendez-le exécutable :

   chmod +x .git/hooks/pre-receive

3. Définissez GITGUARDIAN_API_KEY soit comme une variable d'environnement à l'échelle de la machine, soit dans le fichier .git/hooks/pre-receive comme indiqué dans le fichier d'exemple.

GitHub Enterprise Server

info

La version minimale de GitHub Enterprise Server requise pour prendre en charge les hooks pre-receive est 3.14.

L'installation d'un hook git pre-receive sur GitHub Enterprise Server nécessite 2 composants :

1. un environnement pour exécuter le script,
2. un script exécuté pour chaque événement de push.

Pour plus d'informations, visitez la documentation GitHub Enterprise Server sur le hook pre-receive.

L'environnement pre-receive

Un environnement de hook pre-receive est un chroot Linux. Nous fournissons le script create-ghe-environment pour créer une archive prête à téléverser d'un environnement pre-receive.

Ce script doit être exécuté sur une machine Linux avec Docker installé. Voici comment l'utiliser :

1. Clonez le dépôt ggshield :

   git clone https://github.com/GitGuardian/ggshield.git
   cd ggshield

2. Assurez-vous que la variable d'environnement GITGUARDIAN_API_KEY contient votre clé API.
3. Exécutez le script :

   ./scripts/create-ghe-environment

Lorsque le script est terminé, il devrait afficher un message comme celui-ci :

create-ghe-environment: Storing chroot in ggshield-ghe.tar.gz

Vous pouvez maintenant téléverser ce fichier vers le GitHub Enterprise Server et l'ajouter en utilisant la commande suivante :

ghe-hook-env-create ggshield-environment ~/ggshield-ghe.tar.gz

Ou vous pouvez téléverser ce fichier vers un serveur et passer son URL à l'interface utilisateur web GitHub Enterprise Server pour l'ajouter.

Script

Vous devez ajouter le script suivant à un dépôt hébergé sur GitHub Enterprise Server :

#!/bin/bash

# If you don't use the SaaS product, you need to setup your onprem public api url:
# export GITGUARDIAN_API_URL=<your onprem public api url>
export GITGUARDIAN_API_KEY=$(cat /app/api_key)
/app/.venv/bin/ggshield secret scan pre-receive

Ce fichier de script doit avoir la permission d'exécution. Étant donné que le nom du script apparaît dans le résultat du hook pre-receive, nous recommandons de le nommer pre-receive.sh.

Créer le hook pre-receive

Vous pouvez maintenant suivre la documentation GitHub Enterprise Server pour créer le hook pre-receive.

Ignorer le hook pre-receive

Le hook pre-receive de ggshield peut être ignoré en ajoutant -o breakglass à la commande git push.

Pour que l'option -o breakglass soit prise en compte, le dépôt distant doit avoir l'option de configuration git receive.advertisePushOptions activée.

Cette option peut être activée en exécutant la commande suivante côté serveur :

git config receive.advertisePushOptions true

Certains services d'hébergement Git activent cette option globalement par défaut. D'autres non.

FAQ

Comment éviter de recevoir des alertes pour des secrets déjà détectés sur le tableau de bord GitGuardian ?

Nous vous recommandons d'utiliser l'option --ignore-known-secrets sur le hook pre-receive. Dans ce cas, ggshield ne déclenchera aucune alerte, après que vous exécutez un git push, pour les secrets qui sont déjà connus du tableau de bord GitGuardian (détectés dans des commits précédents et des pull ou merge requests).

Tous les secrets connus seront ignorés, dans les commits poussés et les merge/pull requests, y compris ceux qui ont été codés en dur par d'autres développeurs.

• Pour activer cette option, remplacez ce qui suit dans le hook pre-receive

  ggshield secret scan pre-receive

  par :

  ggshield secret scan pre-receive --ignore-known-secrets

Comment utiliser une configuration personnalisée pour ce hook pre-receive ?

• Créez un gitguardian.yaml quelque part dans le système. Un fichier de configuration d'exemple est disponible ici.

• Remplacez dans le hook pre-receive

  ggshield secret scan pre-receive

  par :

  ggshield -c <INSERT path to gitguardian.yaml> secret scan pre-receive