Detect secrets from all sources using GitGuardian's brains
Project description
ggshield: protect your code with GitGuardian
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 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 and policy breaks incidents will not be displayed on your dashboard and your files and secrets won't be stored.
Table of Contents
- Installation
- Initial setup
- Getting started
- Integrations
- Learn more
- Output
- Related open source projects
- License
Installation
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
Using Homebrew
You can install ggshield
using Homebrew:
$ brew install gitguardian/tap/ggshield
Upgrading is handled by Homebrew.
Using a 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:
Upgrading is handled by the package manager.
All operating systems
ggshield
can be installed on all supported operating systems via its PyPI package.
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:
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.
To catch errors earlier, use ggshield
as a pre-commit, pre-push or pre-receive Git hook.
Learn more
For more information, have a look at the documentation
Output
If no secrets or policy breaks have been found, the exit code will be 0:
$ 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:
$ 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
License
ggshield
is MIT licensed.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for ggshield-1.28.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 80eef0a3daf245a1b28864a6a41ed4aae76c29e0972f2a1f6adce865d801b217 |
|
MD5 | 2432975d1d7f492266b020ee9272a465 |
|
BLAKE2b-256 | 964786ddc489078bce0e2af73bdd3a172b0ba5d25448feca8591f7d8f1354511 |