Bring Your Own Sources
Étendez la détection de secrets à n'importe quelle 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 ainsi une détection de secrets complète sur l'ensemble de votre stack technologique.
Principaux avantages :
- Couverture complète : étendez GitGuardian à n'importe quel système ou source de données de 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 vos 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 des sources personnalisées |
| Périmètre d'équipe | ✅ (Supporté) | Contrôle d'accès basé sur les équipes |
| Vérification de présence | ❌ | Non applicable aux sources de données personnalisées |
| Scan de fichiers | ⏳ (Bientôt) | Les PDF, documents Office, archives, etc. ne sont pas scannés |
Ce que nous scannons :
- Texte brut, logs et fichiers de code
- Couches des images Docker ainsi que dockerfile et arguments de build
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 Growth ou Enterprise pour la fonctionnalité de source personnalisée
- Implémentation de scan personnalisée à 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 :
- Configurez une source personnalisée dans le dashboard GitGuardian ou via l'API GitGuardian.
- 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. - Filtrez, consultez et gérez les incidents de vos sources personnalisées, tout comme avec les intégrations natives dans le dashboard GitGuardian.
Configurer une source personnalisée
Étape 1 : Créer une intégration personnalisée
- Naviguez vers Settings > Integrations > Sources dans votre dashboard GitGuardian.
- Depuis l'onglet Secrets scanning, dans la section Custom Sources, cliquez sur Add Custom Source.

- Donnez à votre source un nom clair (requis) et une description (facultatif).

- Cliquez sur Create Integration. Une fois enregistré, notez l'UUID généré ; vous en aurez besoin sous peu.
Vous pouvez également 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 continuer.
Lors de la création, vous recevrez :
- Un ID d'intégration unique pour attacher des découvertes et déclarer des 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
- Créez un compte de service dédié avec les permissions suivantes :
scanetscan:create-incidents.
Cela permet de scanner et de créer des incidents à partir de vos sources personnalisées. - Configurez votre environnement avec les identifiants nécessaires, en fonction de vos processus internes (par exemple, des variables d'environnement ou une 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
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 des pistes 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 que la vérification de validité ne s'exécute, 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 qui ne peuvent pas être vérifiées. L'option est facultative et définie par source personnalisée.
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, le filtrage s'y produit donc.
Scanner des sources personnalisées avec ggshield
Vous pouvez utiliser notre CLI, ggshield, pour rechercher des secrets exposés dans des fichiers, des répertoires, des logs de build et des 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 vous aider à démarrer.
Utilisez ggshield secret scan --help pour obtenir 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 les logs de build Jenkins
ggshield secret scan path /var/jenkins_home/jobs/*/builds/*/log --source-uuid YOUR_INTEGRATION_ID
Scanner les artefacts GitLab CI
find /builds -name "*.log" -exec ggshield secret scan path {} --source-uuid YOUR_INTEGRATION_ID \+
Scanner les 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 de la requête prend en charge les champs suivants :
| Champ | Requis | Description |
|---|---|---|
filename | ✅ | Un nom ou identifiant pour le document |
document | ✅ | Le contenu texte à scanner |
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 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
- Une fois votre source personnalisée créée, configurez un identifiant Header Auth dans n8n.
- 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
- Ajoutez un nœud Webhook comme déclencheur.
- Copiez son URL de test, puis accédez aux paramètres de votre dépôt GitHub.
- 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 GitGuardian
- Ajoutez un nœud HTTP dans n8n.
- Configurez-le pour envoyer une requête POST à
https://api.gitguardian.com/v1/scan/create-incidentsen utilisant votre identifiant Header Auth. - 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 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.
- Remplacez « my_source » par l'UUID réel de votre source.
- 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.
- Passez en production : activez le workflow.
Voilà ! Vous disposez désormais d'une détection de secrets en temps réel sur vos GitHub Issues.
Filtrer, consulter 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, de sévérité et de statut comme d'habitude.

Consulter les incidents des 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 et contexte complets de l'incident.
- Identification de la source affichant le nom de votre intégration personnalisée.
- Capacité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 :
- Un statut désactivé (ne peut pas être scanné depuis le dashboard).
- Le nom et la description de l'intégration.

Considérations
Limitations actuelles
- Taille des fichiers : 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 source.
- Scan par lots : les grands ensembles de données doivent être scannés par lots pour des performances optimales.
Considérations de performance
- Limites de débit de l'API : l'API GitGuardian limite les lots à 20 documents par appel.
- Grands répertoires : scanner des répertoires contenant plus de 20 fichiers entraînera plusieurs appels d'API.
- Délais d'attente réseau : tenez compte de la stabilité du réseau pour les opérations de scan de grande ampleur.
Améliorations futures
- Prise en charge de plusieurs sources par intégration.
- Augmentation des limites de taille de fichier.
- Capacités de traitement par lots améliorées.
Conseils de pro et bonnes pratiques
Sécurité
- Utilisez un Service Account Token dédié pour chaque source personnalisée.
- Effectuez régulièrement une rotation 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
--recursiveavec discernement sur les 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 pour les sources personnalisées.
- Documentez vos workflows de scan personnalisés pour le partage de connaissances au sein de l'équipe.
Dépannage
Problèmes courants
Erreurs d'authentification
- Vérifiez que votre Service Account Token dispose des permissions
scanetscan:create-incidents. - Assurez-vous que la clé API GitGuardian a été 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 non supprimée.
Erreurs de taille de fichier
- Les fichiers de plus de 50 Mo seront ignorés.
- Utilisez le flag
--verbosepour voir quels fichiers sont ignorés. - Envisagez de diviser les gros fichiers en morceaux plus petits.
Connectivité réseau
- Vérifiez la connectivité réseau vers 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 obtenir une assistance 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 de 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 des utilisateurs
Lors de la mise en œuvre du scan de sources personnalisées, pensez à 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 potentielles fuites 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 façon dont nous gérons vos données personnelles et pour exercer vos droits, veuillez consulter notre avis 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 à des fins professionnelles.
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 :
- Naviguez vers Sources integration
- Cliquez sur Edit à côté du nom de l'intégration
- Cliquez sur Configure
- Cliquez sur l'icône delete à côté de votre ressource
- 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.