Bring Your Own 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 héritées et des outils personnalisés où des secrets peuvent se cacher au-delà des intégrations standard. Bring Your Own Sources comble cet écart en vous permettant de scanner les logs CI/CD, les bases de données héritées, les scripts internes, les partages de fichiers et tout système propriétaire où les développeurs pourraient stocker ou exposer accidentellement des identifiants, garantissant une détection complète des secrets à travers toute votre stack technologique.

Avantages clés :

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

Capacités

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

Ce que nous scannons :

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

info

Prérequis de plan : Disponible pour le plan GitGuardian Enterprise. Essayez-le gratuitement avec une période d'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 de scan personnalisé à l'aide de ggshield, de scripts ou d'outils d'automatisation

Fonctionnement

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. Scannez vos sources personnalisées à l'aide de ggshield, de scripts simples ou d'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. Dans 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 (facultatif).
4. Cliquez sur Create Integration. Une fois enregistré, notez l'UUID généré ; vous en aurez bientôt besoin.

Vous pouvez également créer votre source personnalisée en utilisant le 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 continuer.

Lors de la création, vous recevrez :

• Un ID d'intégration unique pour attacher les découvertes et déclarer les incidents à votre intégration personnalisée. Vous pouvez le consulter à tout moment après la création.
• Des instructions pour configurer un compte de service.

Étape 2 : Configurer un compte de service

1. Créez un Service Account dédié avec les permissions suivantes : scan et scan:create-incidents.
   Cela permet de scanner et de créer des incidents à partir de vos sources personnalisées.
2. Configurez votre environnement avec les identifiants nécessaires, selon vos processus internes (par exemple, variables d'environnement ou connexion directe à votre gestionnaire de secrets, 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 compte de service dédié pour chaque intégration de source personnalisée afin de maintenir un contrôle d'accès et une piste d'audit appropriés.

Scanner uniquement avec des détecteurs validés

Une source personnalisée peut être configurée pour ne conserver que les secrets dont le détecteur prend en charge les vérifications de validité. Lorsque cette option est activée, un scan lié à la source écarte les correspondances des détecteurs qui n'ont pas de validateur avant l'exécution de la vérification de validité, de sorte que seuls les secrets dont la validité peut être vérifiée sont transformés en incidents.

Cela réduit le bruit sur les sources qui génèrent de nombreuses correspondances non vérifiables. Cette option est opt-in et se définit par source personnalisée.

remarque

Ce filtrage s'applique aux scans liés à une source personnalisée, qu'ils soient exécutés avec ggshield (--source-uuid) ou via l'API POST /v1/scan/create-incidents. Les incidents sont créés côté serveur, donc le filtrage s'effectue à cet endroit.

Scanner des sources personnalisées avec ggshield

Vous pouvez utiliser notre CLI, ggshield, pour scanner 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 découvertes soient attachées à votre source de données personnalisée dans le dashboard GitGuardian.
Voici quelques exemples pour commencer.
Utilisez ggshield secret scan --help pour plus de détails.

Scanner des fichiers

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

Scanner des répertoires

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

Scanner des logs de build Jenkins

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

Scanner des artefacts GitLab CI

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

Scanner des logs d'application

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

Scanner des images Docker

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

Scanner des sources personnalisées directement via l'API

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

Champ	Requis	Description
filename	✅	Un nom ou un identifiant pour le document
document	✅	Le contenu textuel à scanner
location.url	❌	Une URL pointant vers l'origine du document (par exemple, une page wiki, un ticket ou un fichier de config). Affichée dans les détails de l'incident pour naviguer facilement 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"
      }
    }
  ]
}

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

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

Étape 1 : Configurer l'authentification GitGuardian

1. Une fois votre source personnalisée créée, configurez un identifiant 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 nœud 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 se déclencher sur les événements « Issues ».

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

1. Ajoutez un nœud HTTP dans n8n.
2. Configurez-le pour envoyer une requête POST à https://api.gitguardian.com/v1/scan/create-incidents en utilisant votre identifiant 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 relie le document à son origine (par exemple, une page wiki, un ticket ou une page de config). Lorsqu'elle est fournie, cette URL apparaît dans les détails de l'incident dans le dashboard GitGuardian, ce qui facilite la navigation vers la source.

4. Remplacez "my_source" par l'UUID réel de votre 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 apparaître votre premier incident de sécurité dans votre dashboard GitGuardian.
6. Passez en production : activez le workflow.

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

Filtrer, visualiser et gérer les incidents

Les sources personnalisées et leurs incidents apparaissent dans le dashboard GitGuardian, tout 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 standard : 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 Détails d'incident :

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

Visibilité du périmètre

Les sources personnalisées apparaissent dans le Monitored Perimeter avec :

• Statut désactivé (ne peut pas être scanné 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 de l'API.
• Sources par intégration : chaque intégration personnalisée prend en charge une seule source.
• Scan par lot : les grands ensembles de données doivent être scannés par lots pour des performances optimales.

Considérations sur les performances

• Limites de débit de l'API : l'API GitGuardian limite les lots à 20 documents par appel.
• Grands répertoires : le scan de répertoires contenant plus de 20 fichiers entraînera plusieurs appels d'API.
• Timeouts réseau : tenez compte de la stabilité du réseau pour les opérations de scan volumineuses.

Améliorations futures

• Prise en charge de plusieurs sources par intégration.
• Augmentation des limites de taille de fichier.
• Amélioration des capacités de traitement par lot.

Astuces et bonnes pratiques

Sécurité

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

Performance

• Scannez les fichiers par lots plutôt qu'individuellement lorsque c'est possible.
• Utilisez le flag --recursive judicieusement avec de grandes arborescences de répertoires.
• Surveillez l'utilisation de l'API pour éviter la limitation de débit.
• Envisagez de planifier les scans 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.
• Mettez en œuvre des conventions de nommage cohérentes entre les sources personnalisées.
• Documentez vos workflows de scan personnalisés pour le partage des connaissances au sein de l'équipe.

Dépannage

Problèmes courants

Erreurs d'authentification

• Vérifiez que votre Service Account Token possède les permissions scan et scan:create-incidents.
• Assurez-vous que la clé API GitGuardian est correctement configurée pour ggshield ou votre script personnalisé.
• Vérifiez que l'URL de votre 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 votre 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 plus petits morceaux.

Connectivité réseau

• Vérifiez la connectivité réseau à votre instance GitGuardian.
• Vérifiez les règles de pare-feu et les configurations de proxy.
• Consultez le 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 de la CLI.
• Consultez la documentation de l'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 aux utilisateurs

Lors de la mise en œuvre du scan 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 pourriez utiliser :

Dans le cadre de notre processus interne de sécurité de l'information, l'entreprise scanne les sources de données personnalisées à la recherche de fuites potentielles de secrets à l'aide de GitGuardian. Toutes les données collectées seront traitées dans le but de détecter d'éventuelles fuites. Pour en savoir plus sur la manière dont nous gérons vos données personnelles et exercer 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 à l'activité professionnelle peuvent être surveillés et que les utilisateurs doivent s'abstenir d'inclure des données personnelles ou sensibles non pertinentes pour l'activité professionnelle.

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.