GitGuardian ggshield

Added

• ggshield ai discover --activity now also collects raw AI-agent activity

(transcript lines / database rows) from Claude Code, Codex, Cursor, Copilot

CLI and VSCode and ships it to GitGuardian, which scans the content and strips

secrets server-side. This is an experimental feature.

• ggshield now officially supports Python 3.13: it is covered by the CI test matrix, advertised through the trove classifiers, and pip install ggshield works on a Python 3.13 interpreter.

• AI discovery now sends whether hooks are installed globally, per agent.

• ggshield machine setup sets up all of this machine's ggshield protections in one idempotent command: the AI hook for every detected AI coding assistant, the global git pre-commit/pre-push hooks, and a honeytoken. Each protection is on by default; drop one with --no-ai-hooks / --no-git-hooks / --no-honeytokens. Narrow which assistants get the AI hook with --agent / --exclude-agent. Replaces running ggshield install -t <assistant> once per agent.

• ggshield machine setup now installs git hooks machine-wide (for every user) when run as root or with the new --system flag, instead of only for the invoking user. This makes MDM/fleet deployments work as expected: a single root-run machine setup sets git's system core.hooksPath, so every user on the machine is covered. Without root (and without --system) it keeps installing per-user as before.

• ggshield machine doctor checks that this machine's ggshield protections are correctly set up: the AI hooks and git hooks are installed, the GitGuardian token is reachable and carries the scopes the configured protections need (scan, plus honeytokens:write and — when the machine_scan plugin is installed — endpoints:send, both of which require a Business or Enterprise plan), and that the plugin's native scanner loads. It is read-only, prints a specific fix for each failed check, and exits non-zero if any check fails, so it can gate an MDM rollout.

• Scan requests now include Machine-Id and Machine-Username headers

• AI scan requests now include the agent name in the headers sent to the scan route.

• ggshield machine doctor now detects when a higher-precedence git core.hooksPath (a repo-local or user-global one, e.g. Husky or lefthook) shadows the ggshield git hook. Git uses only the most-specific core.hooksPath, so such an override silently bypasses ggshield's system/global hook — doctor reports it as a failed "Git hook precedence" check (per repo) instead of giving a false sense of coverage.
• ggshield machine setup warns at install time when a core.hooksPath override takes precedence in the current context, so its git hook would be shadowed there.

• New --filename-only flag for ggshield secret scan: when set, only the file name (not its full path) is sent to GitGuardian, so incidents record just the filename (e.g. config.py instead of src/app/config.py). Recursive scanning still works.

• Plugins can now be installed machine-wide. Running ggshield plugin install or ggshield plugin enable as root writes to a shared system location so every user on the machine can load the plugin; non-root installs stay per-user as before. A user can still disable an admin-enabled plugin for themselves.

• install.sh now offers to add the install dir to your PATH itself when it's missing, instead of only printing instructions: it detects bash, zsh, fish, and (independent of $SHELL) Nushell and PowerShell on Linux when installed, and updates the matching shell profile. Prompted with a default of yes, silent under -y, skippable with the new --no-modify-path. uninstall.sh reverses the edit.

Changed

• Documented the install script at the top of the README's Installation section, with the curl | bash (Linux/macOS) and irm | iex / curl (Windows) one-liners and a pointer to scripts/install/README.md for the full options and uninstall.

• The documented curl | bash

<a href="https://gitguardian.com/"><img src="https://cdn.jsdelivr.net/gh/gitguardian/ggshield/doc/logo.svg"></a>

---

ggshield: protect your code with GitGuardian

PyPI

Docker Image Version (latest semver)

License

GitHub stars

GitHub Workflow Status

Codecov

ggshield is a CLI application that runs in your local environment or in a CI environment to help you detect more than 500+ types of secrets.

ggshield uses our public API through py-gitguardian to scan and detect potential vulnerabilities in files and other text content.

Only metadata such as call time, request size and scan mode is stored from scans using ggshield, therefore secrets will not be displayed on your dashboard and your files and secrets won't be stored.

Table of Contents

<!-- START doctoc generated TOC please keep comment here to allow auto update -->

<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->

• Installation
• Install script (Recommended)
• macOS
• Homebrew
• Standalone .pkg package
• Linux
• Deb and RPM packages
• Windows
• Chocolatey
• MSI installer
• Standalone .zip archive
• All operating systems
• Using pipx
• Using pip
• Initial setup
• Using ggshield auth login
• Manual setup
• Getting started
• Secrets
• Migrating a legacy configuration file
• Integrations
• AI coding assistants
• Learn more
• Output
• Related open source projects
• License

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

Installation

<!--

Any change made in this section must be replicated in the "Step 1: Install

ggshield" section of the "Getting started" page of ggshield public

documentation.

-->

Install script (Recommended)

The quickest way to install ggshield.

Linux / macOS:

curl -sSfL \
  https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | iex

Or, if you prefer curl (bundled with Windows 10+):

curl.exe -sSL https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | powershell -NoProfile -ExecutionPolicy Bypass -Command -

The script accepts options such as --instance and --plugin (install a

plugin). For the EU workspace or a self-hosted instance, set the

GITGUARDIAN_INSTANCE environment variable (or pass --instance <URL>)

before running.

See scripts/install/README.md for the full list

of options, the other install methods, and how to uninstall.

The methods below install the CLI manually instead.

macOS

Homebrew

You can install ggshield using Homebrew:

brew install ggshield

Upgrading is handled by Homebrew.

Standalone .pkg package

Alternatively, you can download and install a standalone .pkg package from ggshield release page.

This package _does not_ require installing Python, but you have to manually download new versions.

Linux

Deb and RPM packages

Deb and RPM packages are available on Cloudsmith.

Setup instructions:

• Deb packages
• RPM packages

Upgrading is handled by the package manager.

Windows

Chocolatey

ggshield is available via the Chocolatey package manager:

choco install ggshield

MSI installer

Download the MSI installer from the ggshield release page and install it:

msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi

Standalone .zip archive

We provide a standalone .zip archive on ggshield release page.

Unpack the archive on your disk, then add the directory containing the ggshield.exe file to %PATH%.

This archive _does not_ require installing Python, but you have to manually download new versions.

All operating systems

ggshield can be installed on all supported operating systems via its PyPI package.

It requires a supported version of Python (not EOL) (except for standalone packages) and git.

If you don't use our packaged versions of ggshield, please be aware that we follow the Python release cycle and do not support versions that have reached EOL.

Using pipx

The recommended way to install ggshield from PyPI is to use pipx, which will install it in an isolated environment:

pipx install ggshield

To upgrade your installation, run:

pipx upgrade ggshield

Using pip

You can also install ggshield from PyPI using pip, but this is not recommended because the installation is not isolated, so other applications or packages installed this way may affect your ggshield installation. This method will also not work if your Python installation is declared as externally managed (for example when using the system Python on operating systems like Debian 12):

pip install --user ggshield

To upgrade your installation, run:

pip install --user --upgrade ggshield

Initial setup

Using ggshield auth login

To use ggshield you need to authenticate against GitGuardian servers. To do so, use the ggshield auth login command. This command automates the provisioning of a personal access token and its configuration on the local workstation.

You can learn more about it from ggshield auth login documentation.

Manual setup

You can also create your personal access token manually and store it in the GITGUARDIAN_API_KEY environment variable to complete the setup.

Getting started

Secrets

You can now use ggshield to search for secrets:

• in files: ggshield secret scan path -r .
• in repositories: ggshield secret scan repo .
• in Docker images (docker command must be available): ggshield secret scan docker ubuntu:22.04
• in Pypi packages (pip command must be available): ggshield secret scan pypi flask
• and more, have a look at ggshield secret scan --help output for details.

Migrating a legacy configuration file

If ggshield reports that your .gitguardian.yaml (or .gitguardian.yml) config file uses a deprecated format, migrate it to the latest version with:

ggshield config migrate

By default, this looks for the configuration file in the current directory, so run it from the directory containing the file. To run it from anywhere, point ggshield to the file explicitly:

ggshield --config-path path/to/.gitguardian.yaml config migrate

The previous version of the file is kept as a .old backup next to it.

Integrations

You can integrate ggshield in your CI/CD workflow.

To catch errors earlier, use ggshield as a pre-commit, pre-push or pre-receive Git hook.

AI coding assistants

ggshield can scan interactions between you and your AI coding assistant in real time, blocking actions that contain secrets before they are executed.

You can install the hooks with the ggshield install command.

Supported tools: Cursor, Claude Code, Copilot Chat, and Codex.

Learn more

For more information, have a look at the documentation

Output

If no secrets have been found, the exit code will be 0:

ggshield secret scan pre-commit

If a secret is found in your staged code or in your CI, you will have an alert giving you the filename where the secret has been found and a patch giving you the position of the secret in the file:

ggshield secret scan pre-commit

2 incidents have been found in file production.rb

11 | config.paperclip_defaults = {
12 |     :s3_credentials => {
13 |     :bucket => "XXX",
14 |     :access_key_id => "XXXXXXXXXXXXXXXXXXXX",
                            |_____AWS Keys_____|

15 |     :secret_access_key => "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
                                |_______________AWS Keys_______________|

16 |     }
17 | }

Lines that are too long are truncated to match the size of the terminal, unless the verbose mode is used (-v or --verbose).

Related open source projects

• truffleHog
• gitleaks
• gitrob
• git-hound
• AWS git-secrets
• detect-secrets

License

ggshield is MIT licensed.