What is ggscout?

GitGuardian Scout (ggscout) is a command-line application that collects secrets and their metadata from your Secrets Managers and synchronizes this data with your GitGuardian platform.

Why Collect Secrets?

When a secret is leaked in your code repository or exposed in your infrastructure, a critical question arises: Is this secret currently in use, and where? Without an inventory of your production secrets, answering this question is time-consuming and error-prone.

ggscout solves this problem by:

1. Creating an inventory of secrets stored in your Secrets Managers (HashiCorp Vault, AWS Secrets Manager, etc.)
2. Classifying each value with the Secrets Detection Engine before hashing
3. Checking each secret with its provider to learn whether it is still valid, what permissions it grants, who owns it, and when it expires. See Check validity and permissions at the source
4. Hashing these secrets locally using the HMSL algorithm: secrets never leave your infrastructure in clear text
5. Reconciling this inventory with secrets detected by GitGuardian in your codebase or other sources

This reconciliation enables three key capabilities:

1. Extend Detection Coverage

By maintaining an inventory of vaulted secrets, you can detect when these secrets are compromised elsewhere in your perimeter. When GitGuardian detects a leaked secret, it can immediately tell you if it matches a secret currently stored in your vault.

Example: A developer accidentally commits an API key to a public repository. With ggscout, you instantly know this key is from your production HashiCorp Vault and which application uses it.

2. Improve Incident Prioritization

Vaulted secrets come with valuable metadata: vault paths, lease times, rotation policies, associated applications, and environments. This context helps you prioritize which incidents to remediate first.

Example: Two secrets are leaked. One has a 90-day lease and is only used in a development environment. The other has a 365-day lease and is used by a production payment service. The metadata from ggscout helps you prioritize the production secret first.

3. Bootstrap Incident Remediation

By identifying secrets that are not in your vault (unvaulted secrets), ggscout can help you secure them. It can automatically push unvaulted secrets into your Secrets Manager, providing your developers with the vault path to update their code.

Example: GitGuardian detects a hardcoded database password in an old repository. Using ggscout, you can push this secret to your vault and provide developers with the exact path to reference it, streamlining the remediation process.

No secrets get out of your environment!

Secrets values will never leave your environment in clear!

Secrets values are hashed using the HMSL hashing algorithm before they are sent to your GitGuardian workspace. Other non-sensitive metadata like the secret names, paths in the vault, creation date, lease time, etc... are also collected to help you in the remediation process.

Safely collect secrets to ease incident remediation

Once you deployed and configured ggscout in your environment, it runs as follows:

1. It collects the secrets and associated metadata from the Secrets Managers you configured.
2. It classifies each value with the Secrets Detection Engine.
3. It checks each classified secret with its provider: validity, permissions, owner, and expiry.
4. It hashes the secrets using the HMSL hashing algorithm.
5. It sends the collected data to GitGuardian and reconciles it with existing secrets incidents.

That’s it, you can start leveraging these capabilities from your GitGuardian Platform!

Classify secrets with the Secrets Detection Engine

Before hashing, ggscout runs each collected value through the same Secrets Detection Engine used for code scanning: 600+ specific and generic detectors.

Classification is based on the value, not only the key name. A secret stored under a generic name such as CONFIG_3 is recognized if the value matches a detector. A key named MY_TOKEN whose value is disabled is not treated as a credential.

When a detector matches, ggscout attaches that detector to the secret. GitGuardian then derives detector type (generic or specific), secret family, category, and provider, and surfaces them in the NHI inventory. Values that match no detector are still inventoried and labeled Unknown. Nothing is dropped.

ggscout also handles values that contain more than one secret:

• A plain-text file such as a .env is split into one inventory entry per detected secret, each with its own hash, so it can be correlated with leaks of those tokens.
• Sibling fields that form one credential (for example a username and password in the same vault object) are classified together.

Requires ggscout 0.32.0 or later

You must run ggscout 0.32.0 or later for classification to appear in NHI Governance. Pin Docker images and Helm charts to that version or to latest after it ships. Classification is always on: there is nothing to enable in ggscout.toml.

Check validity and permissions at the source

Once a value is classified, ggscout asks the secret's provider four questions, from inside your network, before hashing the value:

• Is it still valid? Can this credential still authenticate, or has it been revoked?
• What can it do? The scopes or permissions the provider reports, such as repo and admin:org for a GitHub token.
• Who owns it? The provider-side account behind the credential, with its admin status when the provider exposes it.
• When does it expire? The expiry date, when the provider sets one.

The answers travel with the hashed secret to GitGuardian and show up in the NHI inventory as a Validity column and filter, and as permissions, owner, and expiry in the identity detail. When the same secret is also in a secret incident, GitGuardian merges both verdicts and keeps the most recent one.

ggscout uses the same validity checkers and secret analyzers as the GitGuardian platform. Every check runs with a fresh fetch, so a verdict is never older than your run schedule.

Why check from ggscout rather than from GitGuardian

GitGuardian already checks the validity of leaked secrets from its own servers. Running the check in ggscout gives you more reliable answers for vaulted secrets:

• Reach: ggscout runs next to the secret. It can reach a self-hosted GitLab, an internal Vault, a database behind a VPN, or any provider that only accepts traffic from your network. From GitGuardian's servers, those checks come back Failed to check.
• No allowlisting: you don't need to open your providers to GitGuardian's IP addresses.
• Coverage: the check runs on every secret ggscout collects, not only on the ones that also appear in an incident. You get the list of revoked credentials still sitting in your vaults, and the overprivileged ones, without waiting for a leak.
• Freshness: verdicts refresh on every run, on the schedule you control.

What gets sent to GitGuardian

Only the outcome: a validity status, the sorted list of scopes, the owner identity reported by the provider (user ID, email, admin flag), the expiry date, and the check time. When a check fails, ggscout sends an error category (timeout, network, rate_limited, revoked, ...) and never the provider's own error text. The secret value itself stays in your network and is hashed as usual.

The validity status is one of:

Status	Meaning
valid	The provider accepted the credential.
invalid	The provider rejected it: revoked, expired, or wrong.
failed_to_check	A check ran but could not decide: timeout, network error, rate limit, or access denied.
not_checked	A checker exists for this detector but did not run, for example because the stage is disabled.
no_checker	No detector matched, or the detector has no checker.

What the check does on the provider

Most checks are read-only calls over outbound HTTPS, such as "who am I" or "list my scopes". A few go further, and you should know about them before enabling checks in a sensitive environment:

• Firebase Cloud Messaging sends a message to a test topic.
• OAuth client-credential checks mint an access token.
• Some checks call a verification endpoint, such as GitLab's runner verify or NuGet's verification key.
• AWS SES credentials are checked over SMTP on port 465, which a proxy does not cover.

Some analyzers read environment variables such as VAULT_ADDR, JENKINS_URL, or SONAR_HOST_URL to reach a self-hosted provider instead of the public default. Set them in ggscout's environment when your credentials belong to your own instances.

Proxies

The check stage does not go through a proxy at a private address. With one configured, checks come back failed_to_check. Give ggscout a direct outbound path to the providers you want checked.

Enabled by default, opt out any time

Checks run on every fetch and fetch-and-send. To turn them off, add a [check] section to your configuration:

[check]
enabled = false

With the Helm chart, set it under inventory.config:

inventory:
  config:
    check:
      enabled: false

Secrets then report not_checked (or no_checker), and the NHI inventory shows the last verdict it received, if any. See Configure validity checks for timeouts and concurrency.

Requires ggscout 0.34.1 or later

Validity, permissions, owner, and expiry require ggscout 0.34.1 or later (Helm chart 0.5.23 or later). On earlier versions, the validity of every vaulted secret stays Unknown in the NHI inventory. The workspace-level validity check setting in Settings > Secrets does not control ggscout: use [check].

Safely store unvaulted secrets

With ggscout, you will be able to identify unvaulted secrets from your incidents list.
What’s more, you will also be able to push these secrets to your Secret Managers and bootstrap the remediation of these incidents!
Here is the standard scenario:

• Once a secret incident is prioritized, you can insert the secret within your Secrets Manager
• Your developers fix their code by properly invoking the secret from the right path provided in the Secret Incident detail
• Once the code fixing is done, revoke the right secret from the vault using the hyperlink provided in the Secret Incident detail

ggscout supports this entire process using the following simple flow:

1. ggscout retrieves the secret incident that has not yet been vaulted.
2. ggscout writes the secret to the specified location.

This capability is optional

You can choose not to grant write access.
You can also restrict the locations where the scout can write secrets (e.g., a temporary path specific to ggscout).

Keep full authority on ggscout execution

Transparency matters!

No sensitive information ever leaves your infrastructure.

Having an external program like ggscout allows you to:

• Have your team control its execution and accesses (e.g. having partial accesses, having one instance for read access and another for write access)
• Have your team monitor what data is being processed

ggscout is auditable.

• You can run the fetch-only mode and write a JSON report on your disk so that you can audit the data collected by ggscout, and ensure no secret values in clear are collected. The data available in the report is exactly the data sent to the GitGuardian in default mode.
• You can request access to the source code

Getting Started

Ready to try ggscout? Head over to the Deploy and configure ggscout page, which includes a Quick Start guide for local testing with the CLI binary or Python package, as well as production deployment options using Docker or Kubernetes.

No GitGuardian Platform Access?

If you are deploying ggscout in a Kubernetes cluster but lack access to the GitGuardian platform, preventing you from sending the hashed secrets, ggbridge is the solution. It establishes a secure, mTLS-authenticated gateway between your network and the GitGuardian platform, enabling ggscout to communicate with the GitGuardian public API and transmit the inventory data.

For detailed setup instructions and additional information, please refer to the ggbridge documentation.