Pre-receive

Prélude

Un hook pre-receive vous permet de rejeter les commits poussés vers un dépôt git s'ils ne valident pas chaque vérification. Veuillez consulter notre centre d'apprentissage pour plus d'informations.

Le hook pre-receive de 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.

Comme 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 hook pre-receive pour 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 l'évaluation des 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 GitHub sur les hooks pre-receive.

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 poursuivre leur travail.

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

GitLab Self-Managed et Bitbucket Server

Installer le hook git pre-receive ggshield

Le script d'exemple est disponible dans pre-receive.sample.

1. Ce hook pre-receive nécessite que la machine hôte dispose de 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 des hooks git de votre fournisseur

   • GitLab
   • Bitbucket Server/Datacenter

4. Rendez le script 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 à 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 dans lequel les dépôts sont stockés doit également être monté sur le conteneur.

Le script d'exemple est disponible dans pre-receive-docker.sample

Ce hook pre-receive nécessite que la machine hôte dispose de 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 variable d'environnement globale à 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 la 3.14.

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

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

Pour plus d'informations, consultez la documentation de GitHub Enterprise Server sur les hooks 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 sur GitHub Enterprise Server et l'ajouter à l'aide de la commande suivante :

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

Ou vous pouvez téléverser ce fichier sur un serveur et transmettre son URL à l'interface web de 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 les permissions d'exécution. Puisque 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 dashboard 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 l'exécution d'un git push, pour les secrets déjà connus du dashboard 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 sur le système. Un exemple de fichier de configuration 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