<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 400+ types of secrets, as well as other potential security vulnerabilities or policy breaks affecting your codebase.
`ggshield` uses our [public API](https://api.gitguardian.com/doc) 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 and policy breaks incidents 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)
- [Requirements](#requirements)
- [macOS](#macos)
- [Homebrew](#homebrew)
- [Standalone .pkg package](#standalone-pkg-package)
- [Linux](#linux)
- [Deb and RPM packages](#deb-and-rpm-packages)
- [Windows](#windows)
- [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)
- [Infra as Code Security (IaC)](#infra-as-code-security-iac)
- [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.
-->
## Requirements
`ggshield` works on macOS, Linux and Windows.
It requires **Python 3.8 and newer** (except for standalone packages) and git.
Some commands require additional programs:
- docker: to scan docker images.
- pip: to scan pypi packages.
## macOS
### Homebrew
You can install `ggshield` using Homebrew:
```shell
$ brew install gitguardian/tap/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
### 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).
### 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: `ggshield secret scan docker ubuntu:22.04`
- in Pypi packages: `ggshield secret scan pypi flask`
- and more, have a look at `ggshield secret scan --help` output for details.
## Infra as Code Security (IaC)
You can also search for vulnerabilities in your IaC files using the following command:
```
ggshield iac scan all .
```
However, if you are only interested in _new_ potential IaC vulnerabilities, you can run:
```
ggshield iac scan diff --ref=HEAD~1 .
```
Have a look at `ggshield iac scan --help` for more 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 or policy breaks have been found, the exit code will be 0:
```bash
$ ggshield secret scan pre-commit
```
If a secret or other issue is found in your staged code or in your CI, you will have an alert giving you the type of policy break, the filename where the policy break has been found and a patch giving you the position of the policy break in the file:
```shell
$ ggshield secret scan pre-commit
🛡️ ⚔️ 🛡️ 2 policy breaks 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": "https://github.com/GitGuardian/ggshield",
"name": "ggshield",
"maintainer": "GitGuardian",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "cli, devsecops, secrets-detection, security-tools, gitguardian",
"author": "GitGuardian",
"author_email": "support@gitguardian.com",
"download_url": "https://files.pythonhosted.org/packages/f2/bd/333890c00e3e91a7c35709ada1eec80e7cb05010f6a351dc100dc1a50192/ggshield-1.33.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 400+ types of secrets, as well as other potential security vulnerabilities or policy breaks affecting your codebase.\n\n`ggshield` uses our [public API](https://api.gitguardian.com/doc) 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 and policy breaks incidents 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 - [Requirements](#requirements)\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 - [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 - [Infra as Code Security (IaC)](#infra-as-code-security-iac)\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## Requirements\n\n`ggshield` works on macOS, Linux and Windows.\n\nIt requires **Python 3.8 and newer** (except for standalone packages) and git.\n\nSome commands require additional programs:\n\n- docker: to scan docker images.\n- pip: to scan pypi packages.\n\n## macOS\n\n### Homebrew\n\nYou can install `ggshield` using Homebrew:\n\n```shell\n$ brew install gitguardian/tap/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### 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\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: `ggshield secret scan docker ubuntu:22.04`\n- in Pypi packages: `ggshield secret scan pypi flask`\n- and more, have a look at `ggshield secret scan --help` output for details.\n\n## Infra as Code Security (IaC)\n\nYou can also search for vulnerabilities in your IaC files using the following command:\n\n```\nggshield iac scan all .\n```\n\nHowever, if you are only interested in _new_ potential IaC vulnerabilities, you can run:\n\n```\nggshield iac scan diff --ref=HEAD~1 .\n```\n\nHave a look at `ggshield iac scan --help` for more 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 or policy breaks have been found, the exit code will be 0:\n\n```bash\n$ ggshield secret scan pre-commit\n```\n\nIf a secret or other issue is found in your staged code or in your CI, you will have an alert giving you the type of policy break, the filename where the policy break has been found and a patch giving you the position of the policy break in the file:\n\n```shell\n$ ggshield secret scan pre-commit\n\n\ud83d\udee1\ufe0f \u2694\ufe0f \ud83d\udee1\ufe0f 2 policy breaks 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.33.0",
"project_urls": {
"Homepage": "https://github.com/GitGuardian/ggshield"
},
"split_keywords": [
"cli",
" devsecops",
" secrets-detection",
" security-tools",
" gitguardian"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "75a038296e597e25235d809047223b582edfcf5d27740f474a131764c608d590",
"md5": "c99e05827c55be5774ec0c56e07cb328",
"sha256": "b2e0b79f92825a4d5a04cf4170ec6ea0aeccc63d7650de1cb75d99f767778e40"
},
"downloads": -1,
"filename": "ggshield-1.33.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c99e05827c55be5774ec0c56e07cb328",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 228406,
"upload_time": "2024-10-29T14:52:37",
"upload_time_iso_8601": "2024-10-29T14:52:37.563981Z",
"url": "https://files.pythonhosted.org/packages/75/a0/38296e597e25235d809047223b582edfcf5d27740f474a131764c608d590/ggshield-1.33.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f2bd333890c00e3e91a7c35709ada1eec80e7cb05010f6a351dc100dc1a50192",
"md5": "1d22bfde8c25baea05ce169bbf609876",
"sha256": "722f35f696b99ede1ee14cc469b61784d58f7f08c3a9b3d7d71e6e1107dc54d2"
},
"downloads": -1,
"filename": "ggshield-1.33.0.tar.gz",
"has_sig": false,
"md5_digest": "1d22bfde8c25baea05ce169bbf609876",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 155173,
"upload_time": "2024-10-29T14:52:39",
"upload_time_iso_8601": "2024-10-29T14:52:39.335546Z",
"url": "https://files.pythonhosted.org/packages/f2/bd/333890c00e3e91a7c35709ada1eec80e7cb05010f6a351dc100dc1a50192/ggshield-1.33.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-29 14:52:39",
"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
