Intégration GitLab
GitGuardian Scout (ggscout) peut être configuré pour collecter les secrets et les variables CI/CD des instances GitLab, vous permettant d'inventorier et de surveiller les secrets stockés dans votre environnement GitLab.
Présentation
L'intégration GitLab permet à ggscout de :
- Collecter les variables CI/CD des projets, groupes et de l'instance GitLab
- Inventorier les secrets stockés dans les paramètres de variables CI/CD de GitLab
Prérequis
Avant de configurer l'intégration GitLab, assurez-vous de disposer de :
- Accès à une instance GitLab (GitLab.com ou GitLab auto-hébergé)
- Personal Access Token ou Project/Group Access Token avec les permissions appropriées
- Token d'API GitGuardian avec les permissions NHI
- ggscout déployé dans votre environnement (Docker, Kubernetes ou installation locale)
Configuration
1. Token d'accès GitLab
Créez un token d'accès GitLab avec le scope read_api.
GitLab ne renvoie les variables CI/CD qu'à un token disposant d'un rôle suffisamment élevé. ggscout ignore tout projet ou groupe où le rôle du token est trop faible, de sorte qu'un token avec un rôle faible produit un inventaire qui semble complet mais qui est en grande partie vide.
| Variables collectées | Rôle requis par GitLab |
|---|---|
| Variables de projet | Maintainer ou Owner sur le projet |
| Variables de groupe | Owner sur le groupe |
| Variables d'instance | Administrator (GitLab auto-géré uniquement) |
Avec un token d'administrateur, ggscout collecte les variables de chaque projet et groupe de l'instance, y compris ceux dont l'administrateur n'est pas membre. Avec tout autre token, il collecte les projets et groupes où le token dispose du rôle indiqué ci-dessus.
Pour les Personal Access Tokens :
- Allez dans GitLab → User Settings → Access Tokens
- Créez un nouveau token avec le scope
read_api - Notez la valeur du token de manière sécurisée
Pour les Project ou Group Access Tokens :
- Allez dans Project (ou Group) → Settings → Access Tokens
- Créez un token avec le rôle
Maintainerpour un projet, ou le rôleOwnerpour un groupe - Sélectionnez le scope
read_api
2. Configuration de base
Ajoutez la source GitLab à votre fichier de configuration ggscout :
[sources.gitlab]
type = "gitlabci"
token = "${GITLAB_CI_TOKEN}" # GitLab access token
url = "https://gitlab.com/" # Your GitLab instance URL
env = "production" # Optional: Environment label
owner = "devops-team@example.com" # Optional: Owner of this source
[gitguardian]
api_token = "${GITGUARDIAN_API_KEY}"
endpoint = "https://api.gitguardian.com/v1"
3. Variables d'environnement
Définissez les variables d'environnement requises :
# GitLab access token
GITLAB_CI_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"
# GitGuardian API token
GITGUARDIAN_API_KEY="your-gitguardian-api-key"
Configuration avancée
GitLab auto-hébergé
Pour les instances GitLab auto-hébergées :
[sources.gitlab-selfhosted]
type = "gitlabci"
token = "${GITLAB_CI_TOKEN}"
url = "https://gitlab.example.com/" # Your GitLab instance URL
Plusieurs instances GitLab
Vous pouvez configurer plusieurs sources GitLab :
[sources.gitlab-saas]
type = "gitlabci"
token = "${GITLAB_SAAS_TOKEN}" # Token for GitLab.com
url = "https://gitlab.com/"
[sources.gitlab-onprem]
type = "gitlabci"
token = "${GITLAB_ONPREM_TOKEN}" # Token for self-hosted instance
url = "https://gitlab.internal.com/"
Filtrage des ressources
Vous pouvez filtrer les ressources GitLab que ggscout collecte en utilisant des motifs d'inclusion et d'exclusion :
[sources.gitlab-filtered]
type = "gitlabci"
token = "${GITLAB_CI_TOKEN}"
url = "https://gitlab.com/"
env = "production"
owner = "devops-team@example.com"
# Include only specific projects or groups
[[sources.gitlab-filtered.include]]
resource_ids = ["my-group/*", "important-project"]
# Exclude test or development projects
[[sources.gitlab-filtered.exclude]]
resource_ids = ["*/test-*", "dev-*", "sandbox/*"]
Paramètres de configuration
| Paramètre | Description | Requis | Exemple |
|---|---|---|---|
type | Doit être "gitlabci" | Oui | "gitlabci" |
token | Token d'accès GitLab | Oui | "${GITLAB_CI_TOKEN}" |
url | URL de l'instance GitLab | Oui | "https://gitlab.com/" |
env | Environnement par défaut des secrets de cette source. GitGuardian infère un environnement par secret et se rabat sur cette valeur | Non | "production" |
owner | Propriétaire de cette source (un e-mail, généralement celui d'un employé ou d'une équipe) | Non | "devops-team@example.com" |
include_archived | Collecter aussi les variables des projets archivés, qui peuvent encore contenir des identifiants fonctionnels (par défaut : false) | Non | true |
[[sources.<name>.include]] | Table de motifs de resource_id à inclure | Non | Voir la section filtrage |
[[sources.<name>.exclude]] | Table de motifs de resource_id à exclure | Non | Voir la section filtrage |
Remarque :
- Utilisez les tables
[[sources.<name>.include]]et[[sources.<name>.exclude]]pour spécifier plusieurs règles d'inclusion/exclusion. Chaque table doit avoir un tableauresource_ids. - Les motifs ne prennent en charge les jokers (*) qu'à la fin pour la correspondance de préfixe. Pour des correspondances exactes, spécifiez le nom complet sans joker.
Exécution de ggscout
Utilisation de Docker
Créez un fichier .env :
GITLAB_CI_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITGUARDIAN_API_KEY=your-gitguardian-api-key
Puis exécutez ggscout pour collecter les données GitLab :
docker run --rm -ti \
-v ${PWD}/config.toml:/tmp/config.toml:ro \
--env-file .env \
ghcr.io/gitguardian/ggscout/chainguard:latest \
fetch-and-send /tmp/config.toml
Utilisation de Helm
Déployez ggscout avec l'intégration GitLab à l'aide du chart Helm officiel :
# Add the ggscout Helm repository
helm repo add ggscout https://gitguardian.github.io/ggscout-helm-charts
helm repo update
# Create a values file for GitLab integration
cat > gitlab-values.yaml << EOF
config:
sources:
gitlab:
type: "gitlabci"
token: "${GITLAB_CI_TOKEN}"
url: "https://gitlab.com/"
gitguardian:
api_token: "${GITGUARDIAN_API_KEY}"
endpoint: "https://api.gitguardian.com/v1"
secrets:
GITLAB_CI_TOKEN: "glpat-xxxxxxxxxxxxxxxxxxxx"
GITGUARDIAN_API_KEY: "your-gitguardian-api-key"
schedule: "0 */6 * * *" # Run every 6 hours
EOF
# Install ggscout with GitLab integration
helm install ggscout-gitlab ggscout/ggscout -f gitlab-values.yaml
Données collectées
L'intégration GitLab collecte les données suivantes :
- Variables de projet : variables CI/CD définies sur chaque projet
- Variables de groupe : variables CI/CD définies sur chaque groupe. GitLab ne les renvoie pas avec les variables de projet, donc ggscout les collecte séparément
- Variables d'instance : variables CI/CD définies pour l'ensemble de l'instance, avec un token d'administrateur
- Métadonnées des variables : noms des variables, scopes d'environnement, et les indicateurs
masked,protectedethiddende chaque variable
Une variable marquée masked and hidden ne verra jamais sa valeur renvoyée par GitLab. ggscout l'inventorie tout de même par son nom et son emplacement, sans hash.
Les projets archivés sont ignorés sauf si include_archived est défini.
La collecte de chaque projet avec un token d'administrateur, include_archived, les variables cachées et les indicateurs de variables nécessitent ggscout 0.36.0 ou une version ultérieure.
Depuis ggscout 0.33.0, l'environment_scope de chaque variable est envoyé à GitGuardian, qui le lit comme l'environnement de la variable lorsqu'il en nomme un (production, staging, etc.) et utilise sinon l'env au niveau de la source. Un scope joker (*) ou un scope de préfixe tel que review/* ne nomme aucun environnement.
Dépannage
Peu ou pas de variables collectées
Vérifiez le rôle du token par rapport au tableau de la section Token d'accès GitLab. ggscout enregistre un avertissement pour chaque projet ou groupe qu'il ne peut pas lire, et lorsque le token ne liste aucun projet du tout.
Mode debug
Activez la journalisation de debug pour résoudre les problèmes :
# Using Docker
docker run --rm -ti \
-v ${PWD}/config.toml:/tmp/config.toml:ro \
--env-file .env \
-e RUST_LOG=debug \
ghcr.io/gitguardian/ggscout/chainguard:latest \
fetch /tmp/config.toml --verbose -o /tmp/inventory.json