Aller au contenu principal

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 :

  1. Accès à une instance GitLab (GitLab.com ou GitLab auto-hébergé)
  2. Personal Access Token ou Project/Group Access Token avec les permissions appropriées
  3. Token d'API GitGuardian avec les permissions NHI
  4. 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éesRôle requis par GitLab
Variables de projetMaintainer ou Owner sur le projet
Variables de groupeOwner sur le groupe
Variables d'instanceAdministrator (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 :

  1. Allez dans GitLab → User Settings → Access Tokens
  2. Créez un nouveau token avec le scope read_api
  3. Notez la valeur du token de manière sécurisée

Pour les Project ou Group Access Tokens :

  1. Allez dans Project (ou Group) → Settings → Access Tokens
  2. Créez un token avec le rôle Maintainer pour un projet, ou le rôle Owner pour un groupe
  3. 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ètreDescriptionRequisExemple
typeDoit être "gitlabci"Oui"gitlabci"
tokenToken d'accès GitLabOui"${GITLAB_CI_TOKEN}"
urlURL de l'instance GitLabOui"https://gitlab.com/"
envEnvironnement par défaut des secrets de cette source. GitGuardian infère un environnement par secret et se rabat sur cette valeurNon"production"
ownerPropriétaire de cette source (un e-mail, généralement celui d'un employé ou d'une équipe)Non"devops-team@example.com"
include_archivedCollecter aussi les variables des projets archivés, qui peuvent encore contenir des identifiants fonctionnels (par défaut : false)Nontrue
[[sources.<name>.include]]Table de motifs de resource_id à inclureNonVoir la section filtrage
[[sources.<name>.exclude]]Table de motifs de resource_id à exclureNonVoir 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 tableau resource_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, protected et hidden de 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