Apportez vos propres sources

Étendez la détection de secrets à toute source de données personnalisée au-delà des intégrations natives de GitGuardian.

Pourquoi utiliser Bring Your Own Sources ?

Chaque organisation possède des systèmes uniques, des plateformes legacy et des outils personnalisés où les secrets peuvent se cacher au-delà des intégrations standard. Bring Your Own Sources comble cette lacune en vous permettant d'analyser les logs CI/CD, les bases de données legacy, les scripts internes, les partages de fichiers et tout système propriétaire où les développeurs pourraient stocker ou exposer accidentellement des credentials, garantissant une détection complète des secrets sur l'ensemble de votre stack technologique.

Avantages clés :

• Couverture complète : étendez GitGuardian à n'importe quel système ou source de données dans votre environnement
• Analyse flexible : utilisez des scripts, des outils d'automatisation ou des processus manuels pour alimenter les données
• Surveillance unifiée : gérez les incidents de sources personnalisées aux côtés des intégrations natives
• Approche API-first : intégrez de manière programmatique avec les workflows et toolchains existants

Capacités

Fonctionnalité	Support	Détails
Analyse à la demande	✅	Déclencher les analyses via API ou scripts
Périmètre surveillé	✅	Organisation et catégorisation des sources personnalisées
Périmètre d'équipe	✅ (Pris en charge)	Contrôle d'accès basé sur l'équipe
Vérification de présence	❌	Non applicable pour les sources de données personnalisées
Analyse de fichiers	⏳ (Bientôt disponible)	Les PDF, documents Office, archives, etc. ne sont pas analysés

Ce que nous analysons :

• Texte brut, logs et fichiers de code
• Couches d'images Docker, dockerfiles et arguments de build

info

Exigences de plan : disponible pour les plans GitGuardian Business et Enterprise. Essayez-le gratuitement avec un essai de 30 jours - tous les incidents détectés restent accessibles après la fin de l'essai.
Couverture des détecteurs : pour minimiser les faux positifs, Generic High Entropy Secret et Generic Password sont désactivés. Tous les autres détecteurs sont activés.

Prérequis :

• Compte Owner ou Manager sur votre Dashboard GitGuardian
• Plan Business ou Enterprise pour la fonctionnalité de source personnalisée
• Implémentation d'analyse personnalisée utilisant ggshield, des scripts ou des outils d'automatisation

Comment ça marche

Avec Bring Your Own Sources, connectez n'importe quelle source de données à GitGuardian en quelques minutes :

1. Configurez une source personnalisée dans le dashboard GitGuardian ou via l'API GitGuardian.
2. Analysez vos sources personnalisées en utilisant ggshield, des scripts simples ou un outil d'automatisation.
   Les incidents sont automatiquement créés et liés à votre intégration personnalisée.
3. Filtrez, visualisez et gérez les incidents de vos sources personnalisées comme avec les intégrations natives dans le dashboard GitGuardian.

Configurer une source personnalisée

Étape 1 : créer une intégration personnalisée

1. Naviguez vers Settings > Integrations > Sources dans votre dashboard GitGuardian.
2. Depuis l'onglet Secrets scanning, dans la section Custom Sources, cliquez sur Add Custom Source.
3. Donnez à votre source un nom clair (obligatoire) et une description (facultative).
4. Cliquez sur Create Integration. Une fois enregistré, notez l'UUID généré ; vous en aurez besoin sous peu.

Alternativement, vous pouvez créer votre source personnalisée à l'aide de l'endpoint custom-sources de notre API publique. Vous aurez besoin d'un Service Account Token dédié avec les permissions scan et scan:create-incidents pour procéder.

À la création, vous recevrez :

• Un identifiant d'intégration unique pour attacher des findings et déclarer des incidents à votre intégration personnalisée. Vous pouvez le voir à tout moment après la création.
• Des instructions pour configurer un service account.

Étape 2 : configurer un Service Account

1. Créez un Service Account dédié avec les permissions suivantes : scan et scan:create-incidents.
   Cela permet d'analyser et de créer des incidents à partir de vos sources personnalisées.
2. Configurez votre environnement avec les credentials nécessaires, en fonction de vos processus internes (par exemple, variables d'environnement ou connexion directe à votre secrets manager, etc.) :

export GITGUARDIAN_API_KEY="your-service-account-token"
export GITGUARDIAN_INSTANCE="https://api.gitguardian.com"  # For SaaS US
# export GITGUARDIAN_INSTANCE="https://api.eu1.gitguardian.com"  # For SaaS EU
# export GITGUARDIAN_INSTANCE="https://your-instance.com/exposed"  # For self-hosted

Note de sécurité

Nous recommandons de créer un service account dédié pour chaque intégration de source personnalisée afin de maintenir un contrôle d'accès et des pistes d'audit appropriés.

Analyse de sources personnalisées avec ggshield

Vous pouvez utiliser notre CLI, ggshield, pour analyser les secrets exposés dans les fichiers, répertoires, logs de build et artefacts CI/CD.

Créez des incidents en fournissant l'ID unique de votre intégration afin que les findings soient attachés à votre source de données personnalisée dans le dashboard GitGuardian.
Voici quelques exemples pour bien démarrer.
Utilisez ggshield secret scan --help pour obtenir plus de détails.

Analyser des fichiers

ggshield secret scan path /path/to/file.txt --source-uuid YOUR_INTEGRATION_ID

Analyser des répertoires

ggshield secret scan path -r /path/to/directory --source-uuid YOUR_INTEGRATION_ID

Analyser les logs de build Jenkins

ggshield secret scan path /var/jenkins_home/jobs/*/builds/*/log --source-uuid YOUR_INTEGRATION_ID

Analyser les artefacts GitLab CI

find /builds -name "*.log" -exec ggshield secret scan path {} --source-uuid YOUR_INTEGRATION_ID \+

Analyser les logs d'application

ggshield secret scan path /var/log/legacy-app.log --source-uuid YOUR_INTEGRATION_ID

Analyser des images Docker

ggshield secret scan docker ubuntu:22.04 --source-uuid YOUR_INTEGRATION_ID

Analyse de sources personnalisées en utilisant l'API directement

Vous pouvez envoyer des documents à GitGuardian via l'endpoint POST /v1/scan/create-incidents. Chaque document de la requête prend en charge les champs suivants :

Champ	Requis	Description
filename	✅	Un nom ou identifiant pour le document
document	✅	Le contenu textuel à analyser
location.url	❌	Une URL pointant vers l'origine du document (par exemple, une page wiki, un ticket ou un fichier de configuration). Affichée dans les détails de l'incident pour faciliter la navigation vers l'origine de la fuite.

Exemple :

{
  "source_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "documents": [
    {
      "filename": "document.txt",
      "document": "<content to scan>",
      "location": {
        "url": "https://wiki.example.com/my-config-page"
      }
    }
  ]
}

Analyse de sources personnalisées avec un workflow d'automatisation (par exemple, n8n)

Vous pouvez également utiliser votre outil d'automatisation existant ou des scripts simples pour analyser le contenu de n'importe laquelle de vos sources de données.
Voici un exemple de scénario utilisant n8n pour envoyer le contenu d'Issues GitHub vers GitGuardian via un webhook GitHub.

Étape 1 : configurer l'authentification GitGuardian

1. Une fois votre source personnalisée créée, configurez un credential Header Auth dans n8n.
2. Fournissez les deux valeurs :

• Header Name: Authorization
• Value: Bearer <GG_TOKEN_VALUE> (remplacez par votre token GitGuardian)

Étape 2 : déclencher le workflow avec un webhook GitHub

1. Ajoutez un node Webhook comme déclencheur.
2. Copiez son URL de test, puis allez dans les paramètres de votre dépôt GitHub.
3. Sous Webhooks, ajoutez l'URL n8n et configurez-la pour qu'elle se déclenche sur les événements "Issues".

Étape 3 : envoyer les Issues à l'API de GitGuardian

1. Ajoutez un node HTTP dans n8n.
2. Configurez-le pour envoyer une requête POST à https://api.gitguardian.com/v1/scan/create-incidents en utilisant votre credential Header Auth.
3. Pour le corps de la requête (JSON), utilisez :

{
  "source_uuid": "my_source",
  "documents": [
    {
      "filename": "{{ $json.body.issue.url }}",
      "document": {{ JSON.stringify($json.body.issue.body) }},
      "location": {
        "url": "{{ $json.body.issue.url }}"
      }
    }
  ]
}

Le champ facultatif location.url lie le document à son origine (par exemple, une page wiki, un ticket ou une page de configuration). Lorsqu'il est fourni, cette URL apparaît dans les détails de l'incident dans le dashboard GitGuardian, facilitant la navigation vers la source.

4. Remplacez "my_source" par votre véritable UUID de source.
5. Testez votre workflow en cliquant sur Execute workflow dans n8n, puis créez une Issue dans votre dépôt GitHub — essayez d'inclure un faux secret. Quelques secondes plus tard, vous devriez voir votre premier incident de sécurité apparaître dans votre dashboard GitGuardian.
6. Mise en production : activez le workflow.

Voilà ! Vous avez maintenant une détection de secrets en temps réel sur vos Issues GitHub.

Filtrer, visualiser et gérer les incidents

Les sources personnalisées et leurs incidents apparaissent dans le dashboard GitGuardian comme les intégrations natives.

Filtrage et organisation

Utilisez les filtres du dashboard pour organiser les incidents :

• Integration : sélectionnez l'intégration de source personnalisée.
• Source : filtrez par le nom de source fourni dans votre intégration.
• Source type : sélectionnez Custom Source.
• Filtres standards : appliquez les filtres de date, sévérité et statut comme d'habitude.

Visualiser les incidents de sources personnalisées

Tous les incidents créés à partir de sources personnalisées apparaissent dans les pages Incidents et Incident Details :

• Aperçu du secret dans la liste.
• Détails complets de l'incident et contexte.
• Identification de la source affichant le nom de votre intégration personnalisée.
• Capacités standards de gestion des incidents (assigner, résoudre, ignorer, etc.).

Visibilité dans le périmètre

Les sources personnalisées apparaissent dans le Périmètre surveillé avec :

• Statut désactivé (ne peut pas être analysé depuis le dashboard).
• Nom et description de l'intégration.

Considérations

Limitations actuelles

• Taille de fichier : les fichiers individuels sont limités à 50 Mo en raison des limites d'API.
• Sources par intégration : chaque intégration personnalisée prend en charge une seule source.
• Analyse par lots : les grands ensembles de données doivent être analysés par lots pour des performances optimales.

Considérations de performance

• Limites de taux d'API : l'API GitGuardian limite les lots à 20 documents par appel.
• Grands répertoires : analyser des répertoires avec plus de 20 fichiers entraînera plusieurs appels API.
• Timeouts réseau : tenez compte de la stabilité du réseau pour les opérations d'analyse importantes.

Améliorations futures

• Support de plusieurs sources par intégration.
• Limites de taille de fichier augmentées.
• Capacités améliorées de traitement par lots.

Conseils pro et bonnes pratiques

Sécurité

• Utilisez un Service Account Token dédié pour chaque source personnalisée.
• Faites tourner régulièrement les Service Account Tokens.
• Appliquez le principe du moindre privilège pour les permissions de tokens.
• Évitez de stocker des tokens dans des fichiers en clair.

Performance

• Analysez les fichiers par lots plutôt qu'individuellement lorsque c'est possible.
• Utilisez le flag --recursive judicieusement avec les arborescences de répertoires importantes.
• Surveillez l'utilisation de l'API pour éviter le rate limiting.
• Envisagez de planifier les analyses pendant les heures creuses pour les grands ensembles de données.

Organisation

• Utilisez des noms descriptifs pour les intégrations personnalisées.
• Ajoutez des descriptions significatives pour fournir du contexte aux membres de l'équipe.
• Implémentez des conventions de nommage cohérentes sur toutes les sources personnalisées.
• Documentez vos workflows d'analyse personnalisés pour le partage des connaissances de l'équipe.

Dépannage

Problèmes courants

Erreurs d'authentification

• Vérifiez que votre Service Account Token a les permissions scan et scan:create-incidents.
• Assurez-vous que la clé API GitGuardian a été correctement configurée pour ggshield ou votre script personnalisé.
• Vérifiez que votre URL d'instance est correcte pour les déploiements SaaS ou self-hosted.

ID d'intégration introuvable

• Confirmez que l'ID d'intégration est correctement défini dans votre commande ggshield ou script personnalisé.
• Vérifiez que l'intégration est active et n'a pas été supprimée.

Erreurs de taille de fichier

• Les fichiers de plus de 50 Mo seront ignorés.
• Utilisez le flag --verbose pour voir quels fichiers sont ignorés.
• Envisagez de diviser les gros fichiers en blocs plus petits.

Connectivité réseau

• Vérifiez la connectivité réseau vers votre instance GitGuardian.
• Vérifiez les règles de firewall et les configurations de proxy.
• Référez-vous au guide de dépannage de la connectivité.

Obtenir de l'aide

Pour un support supplémentaire :

• Consultez la documentation ggshield pour l'utilisation générale du CLI.
• Consultez la documentation API pour les intégrations avancées.
• Contactez notre équipe Support à support@gitguardian.com.

Confidentialité et conformité

Gestion des données

GitGuardian traite vos données uniquement pour détecter les secrets exposés :

• Accès en lecture seule : nous ne demandons jamais l'accès en écriture sauf s'il est limité à la création de webhooks pour recevoir et traiter les événements en temps réel
• Rétention minimale des données : nous ne stockons que les données et métadonnées nécessaires à la gestion des incidents
• Chiffrement : toutes les données en transit et au repos sont chiffrées
• Conformité : nous suivons les mêmes standards de protection des données que nos autres intégrations

Considérations régionales

GitGuardian héberge ses services dans deux régions AWS : eu-central-1 (Francfort) et us-west-2 (Oregon). Assurez-vous que votre région de déploiement GitGuardian s'aligne avec vos exigences de résidence des données. Contactez le support si vous avez besoin de conseils sur la conformité aux réglementations locales.

Notification de l'utilisateur

Lors de la mise en œuvre de l'analyse de sources personnalisées, envisagez d'informer les équipes et utilisateurs concernés du processus de détection de secrets. Voici une suggestion de message que vous voudrez peut-être utiliser :

Dans le cadre de notre processus interne de sécurité de l'information, l'entreprise analyse les sources de données personnalisées à la recherche de fuites potentielles de secrets en utilisant GitGuardian. Toutes les données collectées seront traitées dans le but de détecter les fuites potentielles. Pour en savoir plus sur la manière dont nous gérons vos données personnelles et sur l'exercice de vos droits, veuillez vous référer à notre notice de confidentialité employé/partenaire.

Veuillez noter que seuls les systèmes et sources de données liés au business peuvent être surveillés et que les utilisateurs doivent s'abstenir d'inclure des données personnelles ou sensibles non pertinentes à des fins business.

Gérer votre intégration

Surveillance de la santé et maintenance

Si vous devez modifier les paramètres de votre intégration ou résoudre des problèmes de connectivité, accédez à l'interface de gestion via Sources integration.

Désinstaller l'intégration

Bien que notre objectif soit de vous aider à maintenir une couverture de sécurité complète, vous pouvez désinstaller l'intégration chaque fois que nécessaire :

1. Naviguez vers Sources integration
2. Cliquez sur Edit à côté du nom de l'intégration
3. Cliquez sur Configure
4. Cliquez sur l'icône delete à côté de votre ressource
5. Confirmez la suppression

Note : la suppression de l'intégration préserve votre historique d'incidents, mais arrête les analyses futures et les vérifications de présence pour les intégrations qui le supportent.