GitLab Integration

GitGuardian Scout (ggscout) can be configured to collect secrets and CI/CD variables from GitLab instances, enabling you to inventory and monitor secrets stored in your GitLab environment.

Overview

The GitLab integration allows ggscout to:

• Collect CI/CD variables from GitLab projects
• Inventory secrets stored in GitLab CI/CD variable settings

Prerequisites

Before configuring the GitLab integration, ensure you have:

1. GitLab instance access (GitLab.com or self-hosted GitLab)
2. Personal Access Token or Project/Group Access Token with appropriate permissions
3. GitGuardian API token with NHI permissions
4. ggscout deployed in your environment (Docker, Kubernetes, or local installation)

Configuration

1. GitLab Access Token

Create a GitLab access token with the `read_api scope.

For Personal Access Tokens:

1. Go to GitLab → User Settings → Access Tokens
2. Create a new token with required scopes
3. Note the token value securely

For Project Access Tokens:

1. Go to Project → Settings → Access Tokens
2. Create a token with Developer or higher role
3. Select required scopes

2. Basic Configuration

Add the GitLab source to your ggscout configuration file:

[sources.gitlab]
type = "gitlabci"
token = "${GITLAB_CI_TOKEN}"     # GitLab access token
url = "https://gitlab.com/"      # Your GitLab instance URL

[gitguardian]
api_token = "${GITGUARDIAN_API_KEY}"
endpoint = "https://api.gitguardian.com/v1"

3. Environment Variables

Set the required environment variables:

# GitLab access token
GITLAB_CI_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"

# GitGuardian API token
GITGUARDIAN_API_KEY="your-gitguardian-api-key"

Advanced Configuration

Self-Hosted GitLab

For self-hosted GitLab instances:

[sources.gitlab-selfhosted]
type = "gitlabci"
token = "${GITLAB_CI_TOKEN}"
url = "https://gitlab.example.com/"  # Your GitLab instance URL

Multiple GitLab Instances

You can configure multiple GitLab sources:

[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/"

Configuration Parameters

Parameter	Description	Required	Example
type	Must be "gitlabci"	Yes	"gitlabci"
token	GitLab access token	Yes	"${GITLAB_CI_TOKEN}"
url	GitLab instance URL	Yes	"https://gitlab.com/"

Running ggscout

Using Docker

Create a .env file:

GITLAB_CI_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITGUARDIAN_API_KEY=your-gitguardian-api-key

Then run ggscout to collect GitLab data:

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

Using Helm

Deploy ggscout with GitLab integration using the official Helm chart:

# 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

Data Collected

The GitLab integration collects the following data:

• Project Variables: CI/CD variables defined at the project level
• Variable Metadata: Variable names, visibility settings, and environment scopes
• Project Information: Project names, paths, and accessibility

Troubleshooting

Debug Mode

Enable debug logging to troubleshoot issues:

# 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