Configuration

Dépendances entre le dashboard et ggshield

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

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

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

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

Cette information peut être exploitée en utilisant l'option --ignore-known-secrets, qui fait que ggshield ignore les secrets déjà connus de votre dashboard.

Configuration générale

En matière de configuration, vous pouvez affiner le comportement de ggshield à l'aide de trois sources de paramètres. De la priorité la plus haute à la plus basse :

• Options CLI
• Variables d'environnement
• Fichiers de configuration Cela signifie que les options CLI prennent le pas sur les variables d'environnement, qui prennent le pas sur 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 vous recommandons d'utiliser --help avec la commande que vous souhaitez utiliser pour obtenir plus d'informations sur les comportements configurables 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 à partir de 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 trois fichiers d'environnement sera chargé.

Liste des variables d'environnement prises en charge

• GITGUARDIAN_API_KEY : clé API pour l'API GitGuardian. Utilisez-la si vous ne souhaitez pas utiliser les commandes ggshield auth.

• GITGUARDIAN_INSTANCE : URL personnalisée du dashboard GitGuardian. L'URL de l'API en sera déduite.

• GITGUARDIAN_DONT_LOAD_ENV : si elle est définie à n'importe quelle valeur, les variables d'environnement ne seront pas chargées depuis un fichier.

• GITGUARDIAN_DOTENV_PATH : si elle est définie sur un chemin, ggshield tentera de charger l'environnement depuis le fichier spécifié.

• GITGUARDIAN_TIMEOUT : si elle est définie sur un flottant, ggshield secret scan pre-receive expirera après la valeur spécifiée. Définissez à 0 pour désactiver le délai d'expiration.

• GITGUARDIAN_MAX_COMMITS_FOR_HOOK : si elle est définie sur un entier, ggshield secret scan pre-receive et ggshield secret scan pre-push ne scanneront pas plus de la valeur spécifiée de commits dans un seul scan.

• GITGUARDIAN_CRASH_LOG : si elle est définie à True, ggshield affichera une traceback complète en cas de crash.

• GITGUARDIAN_LOG_FILE : si elle est définie sur un fichier, ggshield y enverra la sortie des logs. 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 du global vers le local.

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).

Vous pouvez également utiliser l'option --config-path ou -c 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

Prise en charge 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 magasin de confiance de votre système. Avec Python 3.10 ou ultérieur, ggshield utilise automatiquement le magasin de confiance du système, offrant une validation de certificat sécurisée.

Si vous ne pouvez pas utiliser Python 3.10, l'alternative consiste à utiliser l'option insecure: true, mais cela 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 de type 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 des 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 par groupes de 20 ou moins pour les scanner par appel API. Le scan de dépôts contenant plus de 20 documents entraînera plusieurs appels API.

Vous pouvez approfondir ce sujet 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 fonctionner sur votre instance GitGuardian on-premise.

Tout d'abord, vous devez faire 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 l'administrateur de votre dashboard et en la stockant dans la variable d'environnement GITGUARDIAN_API_KEY.