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 différents :

• Service accounts : un type particulier 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 les pipelines CI ou le traitement par lots d'incidents ouverts.
• Personal access tokens : un jeton destiné à l'utilisation de l'API GitGuardian et de l'application en ligne de commande ggshield par des 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 être versionnée dans Git. (Merci de ne pas pousser les clés API de GitGuardian vers des dépôts GitHub publics ^^).

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

Schéma d'authentification

L'API GitGuardian utilise l'authentification via l'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 utilisant 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 de visualisation, d'édition et de partage sur les incidents de votre workspace GitGuardian.
  • incidents:write : accorde les permissions de visualisation et d'édition sur les incidents de votre workspace GitGuardian.
  • incidents:read : accorde la permission de visualisation uniquement sur les incidents de votre workspace GitGuardian.
• sources
  • sources:write : accorde les permissions de visualisation et d'édition sur les sources (dépôts de code uniquement) de votre workspace GitGuardian.
  • sources:read : accorde la permission de visualisation uniquement sur les sources (dépôts de code uniquement) de votre workspace GitGuardian.
• honeytokens
  • honeytokens:write : accorde les permissions de visualisation 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 la permission de visualisation uniquement 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".
• members
  • members:write : accorde les permissions de visualisation et d'édition sur les membres de votre workspace GitGuardian.
  • members:read : accorde la permission de visualisation sur les membres de votre workspace GitGuardian.
• teams
  • teams:write : accorde les permissions de visualisation et d'édition sur les équipes de votre workspace GitGuardian.
  • teams:read : accorde la permission de visualisation sur les équipes de votre workspace GitGuardian.
• api_tokens
  • api_tokens:write : accorde les permissions de visualisation et d'édition sur les jetons API (personal access tokens et service accounts) de votre workspace GitGuardian.
  • api_tokens:read : accorde la permission de visualisation sur les jetons API (personal access tokens et service accounts) de votre workspace GitGuardian.
• audit_logs:read : accorde la permission de visualisation sur les journaux d'audit de votre workspace GitGuardian. Si vous utilisez des personal access tokens, ce scope n'est disponible que pour les Managers.
• ip_allowlist
  • ip_allowlist:write : accorde les permissions de visualisation et d'édition sur la liste d'autorisation IP de votre workspace GitGuardian.
  • ip_allowlist:read : accorde la permission de visualisation uniquement sur la liste d'autorisation IP de votre workspace GitGuardian.
• custom_tags
  • custom_tags:write : accorde les permissions de visualisation et d'édition sur les tags personnalisés de votre workspace GitGuardian.
  • custom_tags:read : accorde la permission de visualisation uniquement sur les tags personnalisés de votre workspace GitGuardian.
• secrets
  • secrets:write : accorde les permissions de visualisation et d'édition sur les secrets NHI de votre workspace GitGuardian.
  • secrets:read : accorde la permission de visualisation uniquement 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 de visualisation et d'édition sur l'attribution de propriété NHI.
  • nhi:ownership:read : accorde la permission de visualisation uniquement sur l'attribution de propriété NHI.
• public-perimeter:read : accorde la permission de visualisation 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 texte à 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 fonctionnalité directement dans la section Secrets detection playground de votre dashboard :