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.

Vue d'ensemble

L'intégration GitLab permet à ggscout de :

• Collecter les variables CI/CD des projets GitLab
• Inventorier les secrets stockés dans les paramètres des variables CI/CD de GitLab

Prérequis

Avant de configurer l'intégration GitLab, assurez-vous de disposer des éléments suivants :

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.

Pour les Personal Access Tokens :

1. Allez dans GitLab → User Settings → Access Tokens
2. Créez un nouveau token avec les scopes requis
3. Notez la valeur du token en lieu sûr

Pour les Project Access Tokens :

1. Allez dans Project → Settings → Access Tokens
2. Créez un token avec le rôle Developer ou supérieur
3. Sélectionnez les scopes requis

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 à l'aide de 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 retombe 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"
[[sources.<name>.include]]	Table de motifs resource_id à inclure	Non	Voir la section filtrage
[[sources.<name>.exclude]]	Table de motifs resource_id à exclure	Non	Voir la section filtrage

Note :

• 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 une correspondance de préfixe. Pour des correspondances exactes, spécifiez le nom complet sans joker.

Exécuter ggscout

Avec 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

Avec 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 au niveau du projet
• Métadonnées des variables : noms des variables, paramètres de visibilité et portées d'environnement
• Informations sur le projet : noms des projets, chemins et accessibilité

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 le env au niveau de la source. Une portée joker (*) ou une portée de préfixe telle que review/* ne nomme aucun environnement.

Dépannage

Mode débogage

Activez la journalisation de débogage pour diagnostiquer 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