Aller au contenu principal

Secrets Detection Engine

Philosophie​

La détection de secrets est probabiliste : certains secrets sont plus faciles à trouver que d'autres. Il existe un compromis entre un faible nombre de fausses alertes et un faible nombre d'identifiants manqués (compromis précision/rappel)

Notre moteur de détection de secrets est en production depuis 2017, analysant des milliards de commits provenant de GitHub. Dès le premier jour, nous avons commencé à entraîner et à comparer nos algorithmes par rapport au code open source. Cela a permis à GitGuardian de construire un moteur de détection de secrets agnostique au langage, intégrant de nouveaux secrets ou de nouvelles façons de déclarer des secrets très rapidement tout en conservant un très faible nombre de faux positifs. Nous collectons également les retours des alertes que nous envoyons, y compris les alertes pro bono :

  • Retour explicite lorsqu'un développeur ou une équipe de sécurité marque une alerte comme fausse alerte.
  • Retour implicite lorsqu'un développeur supprime un dépôt public ou supprime un commit public quelques minutes après l'envoi d'une alerte.

Nous implémentons actuellement deux types de détecteurs :

  • Détecteurs spécifiques : nous implémentons un algorithme dédié à la recherche d'un type spécifique de secret comme les clés AWS, les URI Postgres ou les identifiants SMTP. Ce type de détecteur vise à avoir un rappel et une précision élevés pour le type de secret ciblé. L'inconvénient de cette approche est que nous devons implémenter beaucoup de détecteurs spécifiques pour avoir une bonne couverture de tous les secrets existants.

  • Détecteurs génériques : le but de ces détecteurs est de capturer ce que nos détecteurs spécifiques manquent avec une approche générique. Nous implémenterons des détecteurs génériques capturant des motifs tels que secret=\{high_entropy_string\} ou password=xxx, email=yyy@corp.com. Nous pouvons ainsi obtenir un faible nombre de secrets manqués même si la précision de ces détecteurs est légèrement inférieure à celle des détecteurs spécifiques.

Vous pouvez bien sûr choisir les détecteurs que vous souhaitez autoriser ou refuser dans nos différentes applications web.

Fonctionnement​

Notre moteur de détection de secrets prend en entrée un Document ayant comme paramètre une chaîne de caractères (un Git Patch, un gist GitHub, un message Slack) et un paramètre facultatif qui est le nom de fichier (secrets.py, index.html, ...) Notez que ce moteur de détection peut utiliser le nom de fichier lorsqu'il est disponible dans une étape de pré-validation : par exemple, nous ne scannerons pas un fichier image ou vidéo puisque personne n'y met de secrets.

Nous avons actuellement les ban-lists suivantes en place :

  1. Nous ne scannons pas les fichiers binaires tels que jpg, tar.*, ...
  2. Nous excluons certains chemins de fichiers à l'aide des regex suivantes :
node_modules(/|\\)
vendors?(/|\\)
top-1000\.txt$
\.sops$
\.sops\.yaml$
  1. Dans la plupart des cas, nous ne scannons pas les documents avec les extensions suivantes car ils apportent beaucoup de faux positifs et presque aucun véritable secret : ["html", "css", "md", "lock", "storyboard", "xib"]

Tao de notre moteur de détection de secrets​

  • 🎯 Précision élevée : nous voulons conserver un faible nombre de faux positifs pour éviter la fatigue liée aux alertes.
  • 🔐 Rappel élevé : nous voulons conserver un faible nombre de secrets manqués pour protéger nos clients.
  • ⚡ Rapidité : bien que la rapidité soit moins importante que le rappel et la précision, notre moteur de détection de secrets est conçu pour être rapide et scanner l'historique d'un dépôt Git courant en moins d'une minute.
  • 👥 Axé sur la communauté et les clients : notre moteur est constamment entraîné et amélioré grâce aux retours de centaines de milliers de développeurs utilisant nos applications et grâce aux retours de nos clients.

Fonctionnalités principales​

Large couverture avec plus de 650 détecteurs​

Nous avons développé une bibliothèque de 680 détecteurs spécifiques et génériques. Consultez la liste des identifiants pris en charge.

Détection de secrets avec correspondances multiples et secrets multi-lignes​

GitGuardian prend en charge la détection de secrets à correspondances multiples tels que les client_id et client_secret oauth, les identifiants de base de données, les identifiants SMTP...

GitGuardian prend en charge la détection de secrets multi-lignes tels que les clés privées.

Par exemple, nous sommes capables de détecter les clés AWS à partir de l'extrait suivant et la sortie sera deux correspondances : une pour le client id et une pour le client secret.

input: 'id=AKIAFJKR45SAWSZ5XDF3, client_secret: hjshnk5ex5u34565d4654HJKGjhz545d89sjkjka'
output:
client_id: AKIAFJKR45SAWSZ5XDF3
client_secret: hjshnk5ex5u34565d4654HJKGjhz545d89sjkjka

Exemple pour les identifiants de base de données :

input: |
dbusername = admin
dbpassword = 8095uohoiw4ur90
dbhost = db-postgres-nyc1-1111-do-user-111111-0.db.ondigitalocean.com
dbport = 25060
dbdatabase = defaultdb
dbsslmode = require
output:
username: admin
password: 8095uohoiw4ur90
host: db-postgres-nyc1-1111-do-user-111111-0.db.ondigitalocean.com
port: 25060

Déduplication automatique​

  • Si deux détecteurs correspondent aux mêmes caractères et ont les mêmes correspondances, nous abandonnons la sortie des détecteurs apportant moins d'informations.

Par exemple, le contenu suivant slack_token="xoxp-198947049743-7861195093-830655328819-9d40a979cac97bccf1190afb660b37e1" déclenche deux détecteurs : notre détecteur slack_user_token et notre détecteur capturant les secrets génériques (token={high_entropy_string}). Nous ne conservons que les résultats du détecteur slack_user_token afin de réduire la fatigue liée aux alertes et d'attacher le maximum d'informations pour aider au processus de remédiation.

Détection de secrets préfixés encodés en Base64​

Les frameworks récents comme Kubernetes utilisent des secrets encodés en Base64 et il devient assez courant de voir des secrets encodés en Base64. Nous sommes capables de détecter les secrets préfixés encodés en Base64 comme les clés privées.

Comment GitGuardian filtre les faux positifs​

Avant que GitGuardian ne signale un secret, chaque correspondance candidate passe par une série de filtres (appelés PostValidators) qui vérifient sa valeur et le code qui l'entoure. Chaque détecteur en combine plusieurs, ajustés à la façon dont les véritables identifiants de ce fournisseur se présentent, de sorte que les valeurs d'exemple, les données de test et le code qui ressemble simplement à une clé ne soient pas signalés comme incidents.

Familles de filtres​

Les filtres se répartissent en sept familles. Chaque détecteur utilise la combinaison qui correspond à son format.

Famille de filtresCe qu'il vérifieFaux positifs qu'il élimine
Aléatoire et mélange de caractèresSi la valeur est aussi aléatoire qu'un véritable identifiant, et si elle a le mélange attendu de lettres et de chiffresCaractères répétés, séquences simples, et noms de variables ou de fonctions qui correspondent par hasard au format d'un token
Détection du langage naturelSi la valeur se lit comme des mots plutôt que des caractères aléatoires, à l'aide d'un grand dictionnaire et de modèles statistiques du langageValeurs telles que MySuperSecretPassword ou default_api_key_value
Valeurs d'exemple et de testLa valeur par rapport à des listes sélectionnées de valeurs d'exemple, d'échantillon et de test connuesyour_api_key, changeme, xxxx, ****, example, test, 12345, et des clés d'échantillon bien connues de la documentation des fournisseurs
Références de code et de modèlesSi la « valeur » est du code qui pointe vers un secret plutôt que le secret lui-mêmeRéférences de variables d'environnement (${API_KEY}, process.env.TOKEN), valeurs d'exemple de modèles, appels de fonction, chemins de fichiers, URL, dates et codes couleur
Contexte environnantLe nom de la variable et le texte à proximité, comparés à des signaux indiquant que la valeur n'est pas un identifiant pour ce fournisseurHachages, sels, signatures et ID, valeurs étiquetées comme invalides ou d'exemple, et identifiants pour un service différent avec un format similaire
Confirmation du fournisseurPour les formats qui ne sont pas uniques à un seul fournisseur, si le nom du fournisseur apparaît près de la valeurChaînes d'apparence générique, telles que des UUID ou des valeurs hexadécimales, qui seraient autrement attribuées à tort à un fournisseur
Validation structurelleLes sommes de contrôle intégrées et les parties des identifiants multi-parties (nom d'utilisateur, mot de passe, hôte)Tokens mal saisis ou inventés qui échouent à la somme de contrôle du fournisseur, chaînes de connexion vers localhost, IP privées ou domaines d'exemple, paires de type admin:admin, et valeurs chiffrées ou hachées qui ne peuvent pas être utilisées

Comment les filtres se combinent​

Moins le format d'un secret est distinctif, plus son détecteur applique de filtres.

  • Les clés spécifiques à un fournisseur avec un préfixe ou une structure reconnaissable reposent principalement sur des vérifications d'aléatoire, plus une validation de somme de contrôle lorsque le fournisseur en intègre une dans ses tokens. Le format seul écarte déjà la plupart des faux positifs.
  • Les clés de fournisseur sans format distinctif ajoutent les filtres de langage naturel, de contexte et de confirmation du fournisseur, de sorte qu'une chaîne aléatoire n'est signalée que lorsque le code qui l'entoure pointe vers ce fournisseur.
  • Les paires d'identifiants et les chaînes de connexion appliquent des vérifications distinctes à chaque partie : listes de valeurs d'exemple sur le nom d'utilisateur et le mot de passe, hôtes non routables ou d'exemple sur l'hôte, et une vérification que le nom d'utilisateur et le mot de passe ne sont pas quasi identiques.
  • Les détecteurs génériques (mots de passe et secrets sans format spécifique à un fournisseur) utilisent l'ensemble le plus large : détection du langage naturel, filtres de code et de modèles, listes de valeurs d'exemple, et rejet des valeurs chiffrées.

GitGuardian ajuste ces filtres en continu par rapport à de grands volumes de code du monde réel, de sorte que la détection reste précise à mesure que de nouveaux formats et conventions de valeurs d'exemple apparaissent.

Ajouter des informations aux secrets pour faciliter le travail des ingénieurs et analystes en sécurité​

Nous attachons des informations aux secrets afin que les analystes en sécurité applicative puissent disposer de plus d'informations contextuelles pour la remédiation. Actuellement, nous prenons en charge les informations suivantes :

  • test_file : nous avons trouvé le secret dans un contexte de test (dossier de test, nom de fichier de test).
  • sensitive_file : nous avons trouvé le secret dans un document dont le nom de fichier est considéré comme sensible (.env, credentials.json, ...).
  • whitelisted : le secret a été mis sur liste blanche par le développeur qui a écrit le code.
  • decoded value for encoded secret : nous pouvons attacher la valeur décodée du secret à un secret encodé.

Limitations​

  1. Nous ne sommes pas capables de scanner les fichiers binaires (pour l'instant). Certains noms de fichiers binaires peuvent contenir des secrets, comme les fichiers .pyc en Python par exemple.
  2. Par défaut, le nombre de secrets détectés par détecteur et par fichier est plafonné à 8. Pour les détecteurs à rappel élevé qui retournent généralement une seule correspondance par document, cette limite est augmentée à 50. Ces seuils aident à prévenir la fatigue liée aux alertes provenant de documents bruyants, tout en gérant les fichiers qui contiennent légitimement de nombreux secrets (tel qu'un fichier avec des dizaines de webhooks Slack). Nous recommandons toujours d'examiner le document complet lorsqu'un secret est détecté, car il peut contenir des informations sensibles supplémentaires qui n'ont pas été remontées.

Architecture​

Notre moteur de détection de secrets est basé sur la logique suivante :

Nous utilisons des PreValidators pour supprimer certains noms de fichiers apportant des faux positifs ou pour sélectionner un document en fonction de la présence d'un mot-clé. Par exemple, chaque SendGrid API key doit commencer par le préfixe SG., nous pouvons écarter tous les documents qui ne contiennent pas ce préfixe. Vous trouverez plus d'informations sur les pré-validateurs ici.

Notre Scanner est une collection de détecteurs qui scanne un Document et produit des candidats Secret.

Nous utilisons ensuite des PostValidators pour valider si nos candidats secrets sont de véritables secrets. Nous configurons les PostValidators pour chaque Detector afin d'obtenir le meilleur compromis entre rappel et précision. Les règles de post-validation filtrent les faux positifs en :

  • Filtrant les clés d'exemple
  • Filtrant les secrets à faible entropie
  • Filtrant les secrets avec des sous-chaînes du dictionnaire anglais
  • Utilisant des modèles de machine learning pour exclure les faux secrets en fonction du contexte

Vous trouverez plus d'informations sur tous les PostValidators que nous utilisons et prenons actuellement en charge ici.