Configuration

Dépendances entre le tableau de bord et ggshield

Le paragraphe suivant décrit comment l'API REST GitGuardian et ggshield (CLI) fonctionnent en relation avec le tableau de bord et comment vous pouvez personnaliser l'expérience du tableau de bord pour qu'elle corresponde au mieux à votre approche du scan de secrets dans les workflows développeurs.

Voici la liste complète des paramètres et interactions entre le tableau de bord et l'API ou la CLI :

Incidents de secrets ignorés
Les secrets dont l'incident associé a été ignoré dans votre tableau de bord GitGuardian ne seront plus signalés par ggshield.
Incidents de secrets résolus
Si le paramètre Regression est OFF, les secrets dont l'incident associé a été résolu dans votre tableau de bord GitGuardian ne seront plus signalés par ggshield. Cependant, si le paramètre Regression est ON, ggshield les signalera.
Détecteurs activés/désactivés
Les secrets associés à des détecteurs que vous avez désactivés dans votre tableau de bord GitGuardian ne seront pas signalés par ggshield.
Vérifications de validité activées/désactivées pour les secrets
ggshield suit le paramètre de vérification de validité de votre tableau de bord GitGuardian. Si ce paramètre est désactivé, ggshield n'effectuera plus de vérifications de validité, et votre tableau de bord non plus.
Exclusions de chemins de fichiers
Les secrets trouvés dans un chemin de fichier exclu dans votre tableau de bord GitGuardian ne seront pas signalés par ggshield.

Pour chaque secret trouvé avec ggshield, nous indiquons s'il est connu de votre tableau de bord GitGuardian. Si un incident de secret existe déjà dans votre tableau de bord GitGuardian, ggshield affichera également l'URL de l'incident de secret associé dans votre console.

Ces informations peuvent être exploitées en utilisant l'option --ignore-known-secrets, qui fait que ggshield ignore les secrets déjà connus de votre tableau de bord.

Configuration générale

En matière de configuration, vous pouvez affiner le comportement de ggshield en utilisant trois sources de paramètres. Par ordre de priorité décroissante :

Options CLI
Variables d'environnement
Fichiers de configuration Cela signifie que les options CLI remplacent les variables d'environnement, qui remplacent les paramètres définis dans les fichiers de configuration.

Options CLI

Quelques paramètres de configuration sont disponibles en tant qu'options CLI. Nous recommandons d'utiliser --help avec la commande que vous avez l'intention d'utiliser pour obtenir plus d'informations sur les comportements qui peuvent être configurés de cette manière.

Variables d'environnement

Certains comportements de ggshield peuvent être ajustés via des variables d'environnement. Au démarrage, ggshield tentera de charger les variables d'environnement depuis différents fichiers d'environnement dans l'ordre suivant :

le fichier pointé par la variable d'environnement GITGUARDIAN_DOTENV_PATH.
Un fichier .env dans le répertoire de travail courant.
Un fichier .env à la racine du répertoire git courant.

Un seul des fichiers env sera chargé parmi les trois.

Liste des variables d'environnement supportées

GITGUARDIAN_API_KEY : clé API pour l'API GitGuardian. Utilisez-la si vous ne voulez pas utiliser les commandes ggshield auth.
GITGUARDIAN_INSTANCE : URL personnalisée du tableau de bord GitGuardian. L'URL de l'API en sera déduite.
GITGUARDIAN_DONT_LOAD_ENV : si définie sur n'importe quelle valeur, les variables d'environnement ne seront pas chargées depuis un fichier.
GITGUARDIAN_DOTENV_PATH : si définie sur un chemin, ggshield tentera de charger l'environnement depuis le fichier spécifié.
GITGUARDIAN_TIMEOUT : si définie sur un float, ggshield secret scan pre-receive expirera après la valeur spécifiée. Définissez sur 0 pour désactiver le timeout.
GITGUARDIAN_MAX_COMMITS_FOR_HOOK : si définie sur un int, ggshield secret scan pre-receive et ggshield secret scan pre-push ne scanneront pas plus que la valeur spécifiée de commits dans un seul scan.
GITGUARDIAN_CRASH_LOG : si définie sur True, ggshield affichera un traceback complet lors d'un crash.
GITGUARDIAN_LOG_FILE : si définie sur un fichier, ggshield enverra la sortie de log vers celui-ci. Vous pouvez également la définir sur - pour envoyer la sortie vers stderr. Équivalent à l'option --log-file.

Fichiers de configuration

La sélection des fichiers de configuration dans ggshield suit une hiérarchie globale à locale.

ggshield cherchera d'abord un fichier de configuration global dans le répertoire personnel de l'utilisateur :

~/.gitguardian.yaml sur Linux ou MacOS
%USERPROFILE%\.gitguardian.yaml sur Windows

ggshield cherchera ensuite un fichier de configuration local dans le répertoire de travail courant (c'est-à-dire ./.gitguardian.yaml).

Alternativement, l'option --config-path ou -c peut être utilisée pour spécifier un fichier de configuration personnalisé :

ggshield --config-path ~/Desktop/custom_config.yaml secret scan path -r .

Dans ce cas, ni les fichiers de configuration locaux ni globaux ne seront évalués.

Voici un exemple de fichier de configuration :

# Required, otherwise ggshield considers the file to use the deprecated v1 format
version: 2

# Set to true if the desired exit code for the CLI is always 0, otherwise the
# exit code will be 1 if incidents are found.
exit_zero: false # default: false

verbose: false # default: false

instance: https://dashboard.gitguardian.com # default: https://dashboard.gitguardian.com

# Maximum commits to scan in a hook.
max_commits_for_hook: 50 # default: 50

# Disable SSL/TLS certificate verification (not recommended).
# Was called `allow_self_signed` before.
insecure: false # default: false

secret:
  # Exclude files and paths by globbing
  ignored_paths:
    - '**/README.md'
    - 'doc/*'
    - 'LICENSE'

  # Ignore security incidents with the SHA256 of the occurrence obtained at output or the secret itself
  ignored_matches:
    - name:
      match: 530e5a4a7ea00814db8845dd0cae5efaa4b974a3ce1c76d0384ba715248a5dc1
    - name: credentials
      match: MY_TEST_CREDENTIAL

  show_secrets: false # default: false

  ignore_known_secrets: false # default: false

  # Detectors to ignore.
  ignored_detectors: # default: []
    - Generic Password

Support des certificats auto-signés

Si votre accès réseau nécessite des certificats auto-signés, l'approche recommandée est d'installer votre certificat dans le trust store de votre système. Avec Python 3.10 ou plus récent, ggshield utilise automatiquement le trust store du système, fournissant une validation sécurisée des certificats.

Si vous ne pouvez pas utiliser Python 3.10, l'alternative est d'utiliser l'option insecure: true, mais ce n'est pas recommandé car cela ignore toutes les vérifications de validation de certificat. Cela signifie que votre connexion à l'API GitGuardian est vulnérable aux attaques man-in-the-middle (MITM). Les clés API, le contenu scanné et les résultats peuvent être interceptés et modifiés.

Limites de taille et considérations sur le volume d'appels API

ggshield s'appuie sur l'API GitGuardian pour effectuer le scan de secrets. La taille maximale d'un document pouvant être scanné est de 1 Mo. Tous les fichiers de plus de 1 Mo seront ignorés. L'utilisation de l'option --verbose affichera des informations sur les fichiers ignorés lors d'un scan de secrets.

L'API GitGuardian limite les lots de fichiers par appel à un maximum de 20 documents. Si un dépôt ou un dossier contient plus de 20 documents, ggshield regroupera les fichiers en groupes de 20 ou moins pour être scannés par appel API. Le scan de dépôts contenant plus de 20 documents entraînera plusieurs appels API.

Vous pouvez explorer ce sujet plus en détail dans la documentation de référence de l'API GitGuardian.

Spécificités pour la configuration on-premise

ggshield peut également être configuré pour s'exécuter sur votre instance GitGuardian on-premise.

Tout d'abord, vous devez pointer ggshield vers votre instance, soit en définissant la clé instance dans votre fichier de configuration .gitguardian.yaml, soit en définissant la variable d'environnement GITGUARDIAN_INSTANCE.

Ensuite, vous devez vous authentifier auprès de votre instance en utilisant la commande ggshield auth login --instance https://mygitguardianinstance.mycorp.local avec l'option --instance, ou en obtenant une clé API auprès de votre administrateur de tableau de bord et en la stockant dans la variable d'environnement GITGUARDIAN_API_KEY.

Configuration

Dépendances entre le tableau de bord et ggshield