Deploy and configure ggscout

ggscout can be executed on-demand as a Command Line Interface (CLI), and deployed in your infrastructure as an autonomous service:

• Using our public Docker Image that embeds ggscout on a dedicated instance
• In a Kubernetes Cluster using our public Helm Chart

ggscout is compatible with self-hosted GitGuardian instances!

The Self-Hosted deployment comes with a ready-to-use Helm chart that you can use to deploy ggscout alongside your GitGuardian instance. Check out the dedicated Self-hosted section.

Overview

GitGuardian Scout (ggscout) is a command-line tool that acts as an outpost in your infrastructure perimeter to collect and synchronize data with your GitGuardian platform. It does not store or transfer any sensitive information - sensitive information is always hashed using the HasMySecretLeaked algorithm.

ggscout supports various integrations with secrets managers, CI/CD systems, and other infrastructure components.

Available Commands

ggscout provides several commands to manage your integrations:

GGScout Commands

• fetch-and-send - Combined operation that fetches data and immediately sends it to GitGuardian platform
• fetch - Run fetchers defined in a configuration file to collect data from your sources, and persist the collected inventory to file storage. This does NOT transfer any data to GitGuardian.
• send - Send previously collected inventory to your GitGuardian platform instance
• sync-secrets - Retrieve secrets from GitGuardian platform and write them to configured destinations
• ping - Test connectivity and send source information to GitGuardian platform

Generic Integration Flow

All ggscout integrations follow a consistent pattern for the fetch and fetch-and-send commands:

1. GitGuardian Authentication

First, if you intend to use any command other than fetch, you need to set up authentication to your GitGuardian platform:

GitGuardian Service Account

ggscout requires specific access rights to communicate with the GitGuardian Platform. Create a service account and select the relevant scopes:

• nhi:send-inventory allows ggscout to send the collected data to GitGuardian
• nhi:write-vault allows ggscout to receive write instructions from GitGuardian.
  See the Secret synchronization section to learn more.

Configuration example

[gitguardian]
api_token = "${GITGUARDIAN_API_KEY}"
endpoint = "${GITGUARDIAN_API_URL}"

And set these variables in your environment, for instance in a .env file:

GITGUARDIAN_API_KEY="your-api-key"
GITGUARDIAN_API_URL="https://api.gitguardian.com/v1"

2. Configuration

Create a TOML configuration file defining your sources and GitGuardian platform connection:

# Source configuration
[sources.my-source]
type = "source_type"
# Source-specific parameters
param1 = "value1"
param2 = "value2"

# GitGuardian platform configuration (required for `fetch-and-send` or `send` commands)
[gitguardian]
api_token = "${GITGUARDIAN_API_KEY}"
endpoint = "${GITGUARDIAN_API_URL}"

See Configure integrations for more general details on how integrations work.

3. Integration Authentication

Set up authentication for your specific integrations using environment variables or direct configuration:

# Additional source-specific environment variables
export HASHICORP_VAULT_TOKEN="your-vault-token"
export AWS_PROFILE="your-aws-profile"
# ... other integration-specific variables

Note that depending on the integration, there may be other authentication methods available that don't require long-lived secrets, such as:

• Kubernetes service account tokens
• IAM roles and OIDC for cloud providers
• Certificate-based authentication
• OAuth flows with short-lived tokens

Check the relevant page in the Integrations section for more details.

4. Execution

For a first manual usage, you would typically run the following commands:

• ping
• fetch
• send

In production, you would configure a recurrent cronjob to run the ping and fetch-and-send commands. See the deployment section below for details.

5. Monitoring

Review the GitGuardian platform to see collected data and manage incidents.

Deployment

Once you have configured ggscout, you can deploy it using various methods depending on your infrastructure needs.

Docker

GitGuardian provides a public docker image on GitHub Container Registry: ghcr.io/gitguardian/ggscout/chainguard. The following example provides the latest version of the image, but you can change the version by replacing the latest tag from the examples.
Consult the list of available releases to learn more.

What's inside the chainguard image

The ggscout Chainguard image is built on Chainguard's distroless base images, specifically designed for enhanced security and minimal attack surface. Chainguard provides secure open source software that is continuously rebuilt from source in secure environments with end-to-end integrity. The Docker image follows distroless principles and contains only 3 layers:

1. Base layer: cgr.dev/chainguard/glibc-dynamic:latest - providing only essential runtime libraries
2. Application layer: Copies the ggscout binary to /usr/bin/ggscout - written in Rust for high performance and security
3. Configuration layer: Sets user to 65532 (nonroot) and configures the entrypoint for secure execution

Available Utilities and Components

The image contains only the ggscout binary - no shell, package managers, or other utilities are included, following distroless principles for maximum security. What's NOT included:

• No shell (/bin/sh, /bin/bash)
• No package managers (apt, yum, apk)
• No debugging utilities
• No text editors
• No system utilities beyond essential runtime libraries

This design aligns with Chainguard's approach of providing minimal, zero-CVE container images that eliminate vulnerabilities while maintaining functionality.

You can manually execute the image using the following commands:

# Ping command
docker run --rm -ti -v ${PWD}:/tmp --env-file .env ghcr.io/gitguardian/ggscout/chainguard:latest ping /tmp/config.toml

# Fetch and send command
docker run --rm -ti -v ${PWD}:/tmp --env-file /path/to/config/dir/.env ghcr.io/gitguardian/ggscout/chainguard:latest fetch-and-send /tmp/config.toml

Use a crontab to configure a recurring job

The Docker image embeds the CLI.
Configure a crontab to configure a recurring job with the commands you need to launch.

Below is an example of the execution with crontab.

# Ping command (every minute)
* * * * * docker run --rm -ti -v /path/to/config/dir:/tmp --env-file /path/to/config/dir/.env ghcr.io/gitguardian/ggscout/chainguard:latest ping /tmp/config.toml

# Fetch and send command (every 5 minutes)
*/5 * * * * docker run --rm -ti -v /path/to/config/dir:/tmp --env-file /path/to/config/dir/.env ghcr.io/gitguardian/ggscout/chainguard:latest fetch-and-send /tmp/config.toml

Replace the /path/to/config/dir where you have configured your config file and your .env file.

Example .env:

GITGUARDIAN_API_KEY=my_gitguardian_api_key
GITLAB_TOKEN=my_gitlab_token
HASHICORP_VAULT_TOKEN=my_vault_token

Helm

You can deploy ggscout on a Kubernetes cluster using ggscout Helm chart.

tip

This is the preferred deployment model if you run ggscout as an autonomous collector periodically.

Deployment instructions are available on our public GitHub repository.
The Helm values allows you to define ggscout configuration in YAML. Examples are provided as templates in the repository.