Deploy and configure ggscout

ggscout can be executed on-demand as a Command Line Interface (CLI).
But it can also be 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.

Configuration file

ggscout configuration file uses the TOML format to describe:

• How ggscout will communicate with GitGuardian platform
• How to access the different Secret Manager to collect secrets

Configuration example:

[gitguardian]
# SaaS
endpoint = "https://api.gitguardian.com/v1"
# Self-hosted
endpoint = "https://my-gg-instance.com/exposed/v1"
api_token = "${GITGUARDIAN_API_KEY}"

[sources.my-hashicorp-vault]
# This lets the Scout know what source to contact
type = "hashicorpvault"
# And this lets the Scout know how to contact it
auth_token = "${VAULT_TOKEN}"
vault_address = "${VAULT_ADDR}"
# Many vaults support secret versioning. Set this to false if you only
# want to collect the latest version of the vault secrets
fetch_all_versions = true
# Allow the Scout instance to read from and write to that vault
mode = "read/write" # "read" and "write" are other possible values
# Optionally restrict the path to collect
path = "secret/some/path/"

[sources.my-other-vault]
# Configure another vault to collect here
type = "gcpsecretmanager"

The config file supports reading environment variables ("${GITGUARDIAN_API_KEY}”) instead of raw values.
Please refer to Secret Managers section to properly configure the collection of secrets.

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 section Safely store unvaulted secrets section to learn more.

Configuration example

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

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.

Docker

GitGuardian provides a public docker image on GitHub Container Registry: ghcr.io/gitguardian/gitguardian-nhi-scout. 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.

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/gitguardian-nhi-scout/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/gitguardian-nhi-scout/chainguard:latest fetch-and-send /tmp/config.toml

# Sync command
docker run --rm -ti -v /path/to/config/dir:/tmp --env-file /path/to/config/dir/.env ghcr.io/gitguardian/gitguardian-nhi-scout/chainguard:latest sync-secrets /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/gitguardian-nhi-scout/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/gitguardian-nhi-scout/chainguard:latest fetch-and-send /tmp/config.toml

# Sync command
* * * * * docker run --rm -ti -v /path/to/config/dir:/tmp --env-file /path/to/config/dir/.env ghcr.io/gitguardian/gitguardian-nhi-scout/chainguard:latest sync-secrets /tmp/config.toml

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