Authentification

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

Créer votre clé API

Il existe 2 types de clés API :

• Comptes de service : un type spécial de jeton destiné à représenter un utilisateur non humain qui doit s'authentifier et être autorisé pour des scénarios tels que le scan de secrets dans des pipelines CI ou le traitement par lot d'incidents ouverts.
• Jetons d'accès personnels : un jeton destiné à l'utilisation de l'API GitGuardian et de l'application en ligne de commande ggshield par les développeurs sur leur poste de travail local (par exemple, dans des hooks git pre-commit ou pre-push).

Vous devez créer un compte pour obtenir une clé API. Votre clé API doit rester confidentielle et ne doit ni être inscrite directement dans le code, ni versionnée dans Git. (Merci de ne pas pousser de clés API GitGuardian sur des dépôts GitHub publics ^^).

Comme dans l'exemple ci-dessous, utilisez l'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. 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

Périmètres (scopes)

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

Scopes de gestion des données du tableau de bord

• incidents
  • incidents:share : accorde les permissions de visualisation, d'édition et de partage sur les incidents de votre espace de travail GitGuardian.
  • incidents:write : accorde les permissions de visualisation et d'édition sur les incidents de votre espace de travail GitGuardian.
  • incidents:read : accorde la permission de visualisation uniquement sur les incidents de votre espace de travail GitGuardian.
• sources
  • sources:write : accorde les permissions de visualisation et d'édition sur les sources (dépôts de code uniquement) de votre espace de travail GitGuardian.
  • sources:read : accorde la permission de visualisation uniquement sur les sources (dépôts de code uniquement) de votre espace de travail GitGuardian.
• honeytokens
  • honeytokens:write : accorde les permissions de visualisation et d'édition sur les honeytokens de votre espace de travail GitGuardian. Disponible sous certaines conditions : le produit honeytoken doit être activé pour l'espace de travail, et pour les jetons d'accès personnels, le rôle doit être au minimum « manager ».
  • honeytokens:read : accorde la permission de visualisation uniquement sur les honeytokens de votre espace de travail GitGuardian. Disponible sous certaines conditions : le produit honeytoken doit être activé pour l'espace de travail, et pour les jetons d'accès personnels, le rôle doit être au minimum « manager ».
• members
  • members:write : accorde les permissions de visualisation et d'édition sur les membres de votre espace de travail GitGuardian.
  • members:read : accorde la permission de visualisation sur les membres de votre espace de travail GitGuardian.
• teams
  • teams:write : accorde les permissions de visualisation et d'édition sur les équipes de votre espace de travail GitGuardian.
  • teams:read : accorde la permission de visualisation sur les équipes de votre espace de travail GitGuardian.
• api_tokens
  • api_tokens:write : accorde les permissions de visualisation et d'édition sur les jetons API (jetons d'accès personnels et comptes de service) de votre espace de travail GitGuardian.
  • api_tokens:read : accorde la permission de visualisation sur les jetons API (jetons d'accès personnels et comptes de service) de votre espace de travail GitGuardian.
• audit_logs:read : accorde la permission de visualisation sur les journaux d'audit de votre espace de travail GitGuardian. Pour les jetons d'accès personnels, ce scope est uniquement disponible pour les Managers.
• ip_allowlist
  • ip_allowlist:write : accorde les permissions de visualisation et d'édition sur la liste d'IP autorisées de votre espace de travail GitGuardian.
  • ip_allowlist:read : accorde la permission de visualisation uniquement sur la liste d'IP autorisées de votre espace de travail GitGuardian.
• custom_tags
  • custom_tags:write : accorde les permissions de visualisation et d'édition sur les tags personnalisés de votre espace de travail GitGuardian.
  • custom_tags:read : accorde la permission de visualisation uniquement sur les tags personnalisés de votre espace de travail GitGuardian.
• secrets
  • secrets:write : accorde les permissions de visualisation et d'édition sur les secrets NHI de votre espace de travail GitGuardian.
  • secrets:read : accorde la permission de visualisation uniquement sur les secrets NHI de votre espace de travail 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 depuis GitGuardian pour la synchronisation des secrets.
  • nhi:ownership:write : accorde les permissions de visualisation et d'édition sur la propriété (ownership) des NHIs.
  • nhi:ownership:read : accorde la permission de visualisation uniquement sur la propriété des NHIs.
• public-perimeter:read : accorde la permission de visualisation sur le périmètre de Public Monitoring de votre espace de travail GitGuardian.

Scope de capacité de scan

• scan : accorde la permission 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 la permission de scanner du contenu et de créer des incidents depuis des sources personnalisées. Inclut le scope scan.

Vous pouvez même tester cette capacité directement depuis la section Secrets detection playground de votre tableau de bord :