Configuration

Dépendances entre le dashboard et ggshield

Le paragraphe suivant décrit comment l'API REST GitGuardian et ggshield (CLI) fonctionnent par rapport au dashboard et comment vous pouvez personnaliser l'expérience du dashboard pour qu'elle corresponde au mieux à votre approche de la détection de secrets dans les flux de travail des développeurs.

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 signalés par ggshield.
• Incidents de secret résolus
  Si le paramètre Regression est sur OFF, les secrets dont l'incident associé a été résolu sur votre dashboard GitGuardian ne seront plus signalés par ggshield. Cependant, si le paramètre Regression est activé (ON), ggshield les signalera.
• 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 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 dashboard GitGuardian. Si ce paramètre est désactivé (OFF), 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 signalé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.

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 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 élevée à la plus faible :

• Options CLI
• Variables d'environnement
• Fichiers de configuration Cela signifie que les options CLI remplacent les variables d'environnement, qui remplacent à leur tour 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 comptez 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 à 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 actuel.
• Un fichier .env à la racine du répertoire git actuel.

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 à une valeur quelconque, les variables d'environnement ne seront pas chargées à partir d'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 float, ggshield secret scan pre-receive expirera après la valeur spécifiée. Définissez-la sur 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 que la valeur spécifiée de commits en un seul scan.

• GITGUARDIAN_CRASH_LOG : Si elle est définie sur True, ggshield affichera une trace complète en cas de plantage.

• 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 globale à locale.

ggshield recherchera 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 recherchera ensuite un fichier de configuration local dans le répertoire de travail actuel (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 le fichier de configuration local ni le fichier de configuration global ne seront évalués.

Voici un exemple de fichier de configuration :

# Obligatoire, sinon ggshield considère que le fichier utilise l'ancien format v1
version: 2

# Définir sur true si le code de sortie souhaité pour la CLI est toujours 0, sinon
# le code de sortie sera 1 si des incidents sont trouvés.
exit_zero: false # default: false

verbose: false # default: false

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

# Nombre maximum de commits à scanner dans un hook.
max_commits_for_hook: 50 # default: 50

# Désactive la vérification du certificat SSL/TLS (non recommandé).
# S'appelait `allow_self_signed` auparavant.
insecure: false # default: false

secret:
  # Exclure les fichiers et chemins par globbing
  ignored_paths:
    - 'LICENSE'           # fichier exact à la racine
    - '*.log'             # tous les fichiers .log dans le répertoire racine
    - 'doc/*'             # tous les fichiers directement à l'intérieur de doc/
    - 'tests/**/*'        # tous les fichiers n'importe où à l'intérieur de tests/
    - '**/*.generated.ts' # tous les fichiers .generated.ts dans n'importe quel répertoire
    - '**/README.md'      # tous les fichiers README.md dans n'importe quel répertoire

  # Ignorer les incidents de sécurité avec le SHA256 de l'occurrence obtenu en sortie ou le secret lui-même
  ignored_matches:
    - name:
      match: 530e5a4a7ea00814db8845dd0cae5efaa4b974a3ce1c76d0384ba715248a5dc1
    - name: credentials
      match: MY_TEST_CREDENTIAL

  show_secrets: false # default: false

  ignore_known_secrets: false # default: false

  # Détecteurs à ignorer.
  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 consiste à installer votre certificat dans le magasin de confiance de votre système. Avec Python 3.10 ou une version ultérieure, ggshield utilise automatiquement le magasin de confiance du système, fournissant une validation de certificat sécurisée.

Si vous ne pouvez pas utiliser Python 3.10, l'alternative est d'utiliser l'option insecure: true, mais cela n'est pas recommandé car elle 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 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. Tout fichier dépassant 1 Mo sera ignoré. 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 à 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 de la configuration on-premise

ggshield peut également être configuré pour fonctionner 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 l'administrateur de votre dashboard et en la stockant dans la variable d'environnement GITGUARDIAN_API_KEY.