Authentification

L'API GitGuardian utilise des clés API pour authentifier les requêtes.

Créer votre clé API

Il existe 2 types différents de clés API :

• Service accounts : un type spécial de token destiné à représenter un utilisateur non humain qui a besoin de s'authentifier et d'être autorisé pour des scénarios tels que le scan de secrets dans les pipelines CI ou le traitement par lots des incidents ouverts.
• Personal access tokens : un token destiné à l'utilisation de l'API GitGuardian et de l'application en ligne de commande ggshield par les développeurs individuels sur leurs postes de travail locaux (par exemple, les hooks git pre-commit ou pre-push).

Vous devez créer un compte afin d'obtenir une clé API. Votre clé API doit être gardée privée et ne doit ni être intégrée directement dans le code, ni versionnée dans Git. (Merci de ne pas pousser les clés API de GitGuardian dans des dépôts GitHub publics ^^).

Comme dans l'exemple ci-dessous, utilisez le endpoint /health pour vérifier la validité de votre clé API.

Schéma d'authentification

L'API GitGuardian utilise l'authentification par en-tête Authorization pour ses requêtes. La valeur de l'en-tête Authorization doit être préfixée par Token.

Exemple de requête avec curl :

curl -H "Authorization: Token ${TOKEN}" \
  https://api.gitguardian.com/v1/health

Scopes

Les scopes sont liés à une clé API et contrôlent l'accès aux ressources ainsi que la capacité de scan.

Scopes de gestion des données du Dashboard

• incidents
  • incidents:share : accorde les permissions d'affichage, d'édition et de partage sur les incidents de votre workspace GitGuardian.
  • incidents:write : accorde les permissions d'affichage et d'édition sur les incidents de votre workspace GitGuardian.
  • incidents:read : accorde uniquement la permission d'affichage sur les incidents de votre workspace GitGuardian.
• sources
  • sources:write : accorde les permissions d'affichage et d'édition sur les sources (dépôts de code uniquement) de votre workspace GitGuardian.
  • sources:read : accorde uniquement la permission d'affichage sur les sources (dépôts de code uniquement) de votre workspace GitGuardian.
• honeytokens
  • honeytokens:write : accorde les permissions d'affichage et d'édition sur les honeytokens de votre workspace GitGuardian. Disponible sous certaines conditions : le produit honeytoken doit être activé pour le workspace, et pour un personal access token, le rôle doit être au minimum "manager".
  • honeytokens:read : accorde uniquement la permission d'affichage sur les honeytokens de votre workspace GitGuardian. Disponible sous certaines conditions : le produit honeytoken doit être activé pour le workspace, et pour un personal access token, le rôle doit être au minimum "manager".
  • honeytokens:check : accorde la permission de vérifier si un secret détecté est un honeytoken, sans exposer les détails du honeytoken. Utilisé par ggshield pendant les scans afin que les honeytokens soient reconnus au lieu d'être traités comme de vrais secrets ou déclenchés accidentellement. Contrairement aux scopes read/write des honeytokens, il ne nécessite pas un rôle Manager.
• members
  • members:write : accorde les permissions d'affichage et d'édition sur les membres de votre workspace GitGuardian.
  • members:read : accorde la permission d'affichage sur les membres de votre workspace GitGuardian.
• teams
  • teams:write : accorde les permissions d'affichage et d'édition sur les équipes de votre workspace GitGuardian.
  • teams:read : accorde la permission d'affichage sur les équipes de votre workspace GitGuardian.
• api_tokens
  • api_tokens:write : accorde les permissions d'affichage et d'édition sur les tokens d'API (personal access tokens et service accounts) de votre workspace GitGuardian.
  • api_tokens:read : accorde la permission d'affichage sur les tokens d'API (personal access tokens et service accounts) de votre workspace GitGuardian.
• audit_logs:read : accorde la permission d'affichage sur les journaux d'audit de votre workspace GitGuardian. Si vous utilisez des personal access tokens, il est disponible uniquement pour les Managers.
• ip_allowlist
  • ip_allowlist:write : accorde les permissions d'affichage et d'édition sur la liste d'IP autorisées de votre workspace GitGuardian.
  • ip_allowlist:read : accorde uniquement la permission d'affichage sur la liste d'IP autorisées de votre workspace GitGuardian.
• custom_tags
  • custom_tags:write : accorde les permissions d'affichage et d'édition sur les tags personnalisés de votre workspace GitGuardian.
  • custom_tags:read : accorde uniquement la permission d'affichage sur les tags personnalisés de votre workspace GitGuardian.
• secrets
  • secrets:write : accorde les permissions d'affichage et d'édition sur les secrets NHI de votre workspace GitGuardian.
  • secrets:read : accorde uniquement la permission d'affichage sur les secrets NHI de votre workspace GitGuardian.
• nhi
  • nhi:send-inventory : accorde la permission d'envoyer des données d'inventaire NHI à GitGuardian.
  • nhi:write-vault : accorde la permission de recevoir des instructions d'écriture de GitGuardian pour la synchronisation des secrets.
  • nhi:ownership:write : accorde les permissions d'affichage et d'édition sur la propriété NHI.
  • nhi:ownership:read : accorde uniquement la permission d'affichage sur la propriété NHI.
• public-perimeter:read : accorde la permission d'affichage sur le périmètre de Public Monitoring de votre workspace GitGuardian.

Scope de capacité de scan

• scan : accorde les permissions de scanner tout contenu textuel à la recherche de secrets avec le moteur de détection de secrets de GitGuardian. Requis pour utiliser ggshield.
• scan:create-incidents : accorde les permissions de scanner du contenu et de créer des incidents à partir de sources personnalisées. Inclut le scope scan.

Vous pouvez même tester cette capacité directement dans la section Secrets detection playground de votre dashboard :