<a href="https://gitguardian.com/"><img src="https://cdn.jsdelivr.net/gh/gitguardian/ggshield/doc/logo.svg"></a>
---
# [ggshield](https://github.com/GitGuardian/ggshield): protect your code with GitGuardian
[](https://pypi.org/project/ggshield/)
[](https://hub.docker.com/r/gitguardian/ggshield)
[](LICENSE)
[](https://github.com/GitGuardian/ggshield/stargazers)
[](https://github.com/GitGuardian/ggshield/actions)
[](https://codecov.io/gh/GitGuardian/ggshield/)
`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](https://api.gitguardian.com/docs) through [py-gitguardian](https://github.com/GitGuardian/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](#installation)
- [macOS](#macos)
- [Homebrew](#homebrew)
- [Standalone .pkg package](#standalone-pkg-package)
- [Linux](#linux)
- [Deb and RPM packages](#deb-and-rpm-packages)
- [Windows](#windows)
- [Chocolatey](#chocolatey)
- [Standalone .zip archive](#standalone-zip-archive)
- [All operating systems](#all-operating-systems)
- [Using pipx](#using-pipx)
- [Using pip](#using-pip)
- [Initial setup](#initial-setup)
- [Using `ggshield auth login`](#using-ggshield-auth-login)
- [Manual setup](#manual-setup)
- [Getting started](#getting-started)
- [Secrets](#secrets)
- [Integrations](#integrations)
- [Learn more](#learn-more)
- [Output](#output)
- [Related open source projects](#related-open-source-projects)
- [License](#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.
-->
## macOS
### Homebrew
You can install `ggshield` using Homebrew:
```shell
$ 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](https://github.com/GitGuardian/ggshield/releases).
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](https://cloudsmith.io/~gitguardian/repos/ggshield/packages/).
Setup instructions:
- [Deb packages](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-deb)
- [RPM packages](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-rpm)
Upgrading is handled by the package manager.
## Windows
### Chocolatey
`ggshield` is available via the [Chocolatey package manager](https://chocolatey.org/packages/ggshield):
```shell
$ choco install ggshield
```
### Standalone .zip archive
We provide a standalone .zip archive on [`ggshield` release page](https://github.com/GitGuardian/ggshield/releases).
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](https://pypi.org/project/ggshield).
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](https://devguide.python.org/versions/) and do not support versions that have reached EOL.
### Using pipx
The recommended way to install `ggshield` from PyPI is to use [pipx](https://pypa.github.io/pipx/), which will install it in an isolated environment:
```shell
$ pipx install ggshield
```
To upgrade your installation, run:
```shell
$ 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):
```shell
$ pip install --user ggshield
```
To upgrade your installation, run:
```shell
$ 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](https://docs.gitguardian.com/internal-repositories-monitoring/ggshield/reference/auth/login).
## 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.
# Integrations
You can integrate `ggshield` in your [CI/CD workflow](https://docs.gitguardian.com/ggshield-docs/integrations/overview#cicd-integrations-secrets-detection-in-your-cicd-workflow).
To catch errors earlier, use `ggshield` as a [pre-commit, pre-push or pre-receive Git hook](https://docs.gitguardian.com/ggshield-docs/integrations/overview#git-hooks-prevent-secrets-from-reaching-your-vcs).
# Learn more
For more information, have a look at [the documentation](https://docs.gitguardian.com/ggshield-docs/getting-started)
# Output
If no secrets have been found, the exit code will be 0:
```bash
$ 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:
```shell
$ 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](https://github.com/dxa4481/truffleHog)
- [gitleaks](https://github.com/zricethezav/gitleaks)
- [gitrob](https://github.com/michenriksen/gitrob)
- [git-hound](https://github.com/tillson/git-hound)
- [AWS git-secrets](https://github.com/awslabs/git-secrets)
- [detect-secrets](https://github.com/Yelp/detect-secrets)
# License
`ggshield` is MIT licensed.
Raw data
{
"_id": null,
"home_page": null,
"name": "ggshield",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "GitGuardian <support@gitguardian.com>",
"keywords": "cli, devsecops, secrets-detection, security-tools, gitguardian",
"author": null,
"author_email": "GitGuardian <support@gitguardian.com>",
"download_url": "https://files.pythonhosted.org/packages/9e/0c/1f827a1559a0e49663b1969c906c8a776ad02d57bb7c1b500477e2331cdd/ggshield-1.42.0.tar.gz",
"platform": null,
"description": "<a href=\"https://gitguardian.com/\"><img src=\"https://cdn.jsdelivr.net/gh/gitguardian/ggshield/doc/logo.svg\"></a>\n\n---\n\n# [ggshield](https://github.com/GitGuardian/ggshield): protect your code with GitGuardian\n\n[](https://pypi.org/project/ggshield/)\n[](https://hub.docker.com/r/gitguardian/ggshield)\n[](LICENSE)\n[](https://github.com/GitGuardian/ggshield/stargazers)\n[](https://github.com/GitGuardian/ggshield/actions)\n[](https://codecov.io/gh/GitGuardian/ggshield/)\n\n`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.\n\n`ggshield` uses our [public API](https://api.gitguardian.com/docs) through [py-gitguardian](https://github.com/GitGuardian/py-gitguardian) to scan and detect potential vulnerabilities in files and other text content.\n\nOnly 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**.\n\n# Table of Contents\n\n<!-- START doctoc generated TOC please keep comment here to allow auto update -->\n<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->\n\n- [Installation](#installation)\n - [macOS](#macos)\n - [Homebrew](#homebrew)\n - [Standalone .pkg package](#standalone-pkg-package)\n - [Linux](#linux)\n - [Deb and RPM packages](#deb-and-rpm-packages)\n - [Windows](#windows)\n - [Chocolatey](#chocolatey)\n - [Standalone .zip archive](#standalone-zip-archive)\n - [All operating systems](#all-operating-systems)\n - [Using pipx](#using-pipx)\n - [Using pip](#using-pip)\n- [Initial setup](#initial-setup)\n - [Using `ggshield auth login`](#using-ggshield-auth-login)\n - [Manual setup](#manual-setup)\n- [Getting started](#getting-started)\n - [Secrets](#secrets)\n- [Integrations](#integrations)\n- [Learn more](#learn-more)\n- [Output](#output)\n- [Related open source projects](#related-open-source-projects)\n- [License](#license)\n\n<!-- END doctoc generated TOC please keep comment here to allow auto update -->\n\n# Installation\n\n<!--\nAny change made in this section must be replicated in the \"Step 1: Install\nggshield\" section of the \"Getting started\" page of ggshield public\ndocumentation.\n-->\n\n## macOS\n\n### Homebrew\n\nYou can install `ggshield` using Homebrew:\n\n```shell\n$ brew install ggshield\n```\n\nUpgrading is handled by Homebrew.\n\n### Standalone .pkg package\n\nAlternatively, you can download and install a standalone .pkg package from [`ggshield` release page](https://github.com/GitGuardian/ggshield/releases).\n\nThis package _does not_ require installing Python, but you have to manually download new versions.\n\n## Linux\n\n### Deb and RPM packages\n\nDeb and RPM packages are available on [Cloudsmith](https://cloudsmith.io/~gitguardian/repos/ggshield/packages/).\n\nSetup instructions:\n\n- [Deb packages](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-deb)\n- [RPM packages](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-rpm)\n\nUpgrading is handled by the package manager.\n\n## Windows\n\n### Chocolatey\n\n`ggshield` is available via the [Chocolatey package manager](https://chocolatey.org/packages/ggshield):\n\n```shell\n$ choco install ggshield\n```\n\n### Standalone .zip archive\n\nWe provide a standalone .zip archive on [`ggshield` release page](https://github.com/GitGuardian/ggshield/releases).\n\nUnpack the archive on your disk, then add the directory containing the `ggshield.exe` file to `%PATH%`.\n\nThis archive _does not_ require installing Python, but you have to manually download new versions.\n\n## All operating systems\n\n`ggshield` can be installed on all supported operating systems via its [PyPI package](https://pypi.org/project/ggshield).\n\nIt requires **a supported version of Python (not EOL)** (except for standalone packages) and git.\n\nIf you don't use our packaged versions of `ggshield`, please be aware that we follow the [Python release cycle](https://devguide.python.org/versions/) and do not support versions that have reached EOL.\n\n### Using pipx\n\nThe recommended way to install `ggshield` from PyPI is to use [pipx](https://pypa.github.io/pipx/), which will install it in an isolated environment:\n\n```shell\n$ pipx install ggshield\n```\n\nTo upgrade your installation, run:\n\n```shell\n$ pipx upgrade ggshield\n```\n\n### Using pip\n\nYou 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):\n\n```shell\n$ pip install --user ggshield\n```\n\nTo upgrade your installation, run:\n\n```shell\n$ pip install --user --upgrade ggshield\n```\n\n# Initial setup\n\n## Using `ggshield auth login`\n\nTo 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.\n\nYou can learn more about it from [`ggshield auth login` documentation](https://docs.gitguardian.com/internal-repositories-monitoring/ggshield/reference/auth/login).\n\n## Manual setup\n\nYou can also create your personal access token manually and store it in the `GITGUARDIAN_API_KEY` environment variable to complete the setup.\n\n# Getting started\n\n## Secrets\n\nYou can now use `ggshield` to search for secrets:\n\n- in files: `ggshield secret scan path -r .`\n- in repositories: `ggshield secret scan repo .`\n- in Docker images (`docker` command must be available): `ggshield secret scan docker ubuntu:22.04`\n- in Pypi packages (`pip` command must be available): `ggshield secret scan pypi flask`\n- and more, have a look at `ggshield secret scan --help` output for details.\n\n# Integrations\n\nYou can integrate `ggshield` in your [CI/CD workflow](https://docs.gitguardian.com/ggshield-docs/integrations/overview#cicd-integrations-secrets-detection-in-your-cicd-workflow).\n\nTo catch errors earlier, use `ggshield` as a [pre-commit, pre-push or pre-receive Git hook](https://docs.gitguardian.com/ggshield-docs/integrations/overview#git-hooks-prevent-secrets-from-reaching-your-vcs).\n\n# Learn more\n\nFor more information, have a look at [the documentation](https://docs.gitguardian.com/ggshield-docs/getting-started)\n\n# Output\n\nIf no secrets have been found, the exit code will be 0:\n\n```bash\n$ ggshield secret scan pre-commit\n```\n\nIf 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:\n\n```shell\n$ ggshield secret scan pre-commit\n\n2 incidents have been found in file production.rb\n\n11 | config.paperclip_defaults = {\n12 | :s3_credentials => {\n13 | :bucket => \"XXX\",\n14 | :access_key_id => \"XXXXXXXXXXXXXXXXXXXX\",\n |_____AWS Keys_____|\n\n15 | :secret_access_key => \"XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\"\n |_______________AWS Keys_______________|\n\n16 | }\n17 | }\n```\n\nLines that are too long are truncated to match the size of the terminal, unless the verbose mode is used (`-v` or `--verbose`).\n\n# Related open source projects\n\n- [truffleHog](https://github.com/dxa4481/truffleHog)\n- [gitleaks](https://github.com/zricethezav/gitleaks)\n- [gitrob](https://github.com/michenriksen/gitrob)\n- [git-hound](https://github.com/tillson/git-hound)\n- [AWS git-secrets](https://github.com/awslabs/git-secrets)\n- [detect-secrets](https://github.com/Yelp/detect-secrets)\n\n# License\n\n`ggshield` is MIT licensed.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Detect secrets from all sources using GitGuardian's brains",
"version": "1.42.0",
"project_urls": {
"Homepage": "https://github.com/GitGuardian/ggshield"
},
"split_keywords": [
"cli",
" devsecops",
" secrets-detection",
" security-tools",
" gitguardian"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "cdfeed65293d70c1c6b5a0f27c3230d72c417f6f9dd20015fc0b43a087810671",
"md5": "741d8c3bbf5b2017419fc9e196f05421",
"sha256": "9bfe1e4b0d899721674b2c3eb09c01d6f54dcd9cd9d9c35b311c742e3817706b"
},
"downloads": -1,
"filename": "ggshield-1.42.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "741d8c3bbf5b2017419fc9e196f05421",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 183967,
"upload_time": "2025-07-29T11:26:31",
"upload_time_iso_8601": "2025-07-29T11:26:31.377671Z",
"url": "https://files.pythonhosted.org/packages/cd/fe/ed65293d70c1c6b5a0f27c3230d72c417f6f9dd20015fc0b43a087810671/ggshield-1.42.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "9e0c1f827a1559a0e49663b1969c906c8a776ad02d57bb7c1b500477e2331cdd",
"md5": "a53b29329f3fa81520e3eeb2c58c5de6",
"sha256": "c897f5ebf3595f0178ea8ee8aab668869782b8aa1e08664ce430c0ca51f93618"
},
"downloads": -1,
"filename": "ggshield-1.42.0.tar.gz",
"has_sig": false,
"md5_digest": "a53b29329f3fa81520e3eeb2c58c5de6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 304612,
"upload_time": "2025-07-29T11:26:32",
"upload_time_iso_8601": "2025-07-29T11:26:32.574213Z",
"url": "https://files.pythonhosted.org/packages/9e/0c/1f827a1559a0e49663b1969c906c8a776ad02d57bb7c1b500477e2331cdd/ggshield-1.42.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-29 11:26:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "GitGuardian",
"github_project": "ggshield",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ggshield"
}
JSON
