Getting started
ggshield
is a CLI application that runs in your local environment or in a CI environment to help you detect more
than 350+ types of secrets, as well as other potential security vulnerabilities or policy breaks affecting your codebase.
ggshield is open source on GitHub and accessible here.
ggshield
can run:
- in your local environment to scan local files and repositories or as a pre-commit hook.
- in a CI environment,
- in a pre-receive hook, if you have a self-managed VCS instance
Note :
ggshield
uses our public API through py-gitguardian to scan files.
Only metadata such as call time, request size and scan mode is stored when launching a scan with ggshield,
therefore secrets and policy breaks incidents will not be displayed on your dashboard and
your files and secrets won't be stored.
#
Step 1: Install ggshieldThe minimum requirements for installing ggshield are:
- python 3.7+
- git
- pip
Note: GitGuardian supports versions of ggshield above and including v1.12.0.
The package runs on MacOS, Linux and Windows.
#
macOS - Using HomebrewYou can install ggshield using Homebrew by running the following command:
$ brew install gitguardian/tap/ggshield
#
Linux packagesDeb and RPM packages are available on Cloudsmith.
Setup instructions:
#
Other Operating Systems - Using pipInstall and update using pip
:
$ pip install ggshield
#
UpdatingTo update ggshield you must add the -U/--upgrade
option to the pip install
command.
$ pip install -U ggshield
#
Step 2: Authenticate with your GitGuardian workspaceggshield
requires an API key to authenticate the CLI with your GitGuardian workspace.
There are 2 different types of API keys:
- Service Accounts: a special type of token intended to represent a non-human user that needs to authenticate and be authorized for scenarios such as secrets scanning in CI pipelines or batch processing open incidents.
- Personal Access Tokens: a token intended for the use of the GitGuardian API and command-line application ggshield by individual developers on their local workstations (e.g. pre-commit or pre-push git hooks).
#
Option 1: AutomaticallyIf you want to set up ggshield for use on your local workstation (e.g. to scan repos or in a pre-commit or pre-push git hook), we recommend running the following command:
ggshield auth login
This will open a new window in your web browser. Simply follow the steps to login to your workspace (or create a new account) and GitGuardian will automatically provision a personal access token and store it in your configuration.
You can find more details in the login command reference section.
#
Option 2: ManuallyYou can also provision your API key manually. This is useful when you want to set up ggshield in your CI environment for example.
#
Create your API keyTo create your API key manually, please follow the steps described in the API authentication section. Once you have your API key ready, follow the rest of the guide on this page.
#
Source your API key in your environmentAlternatively, you can create your personal access token manually and store it in the GITGUARDIAN_API_KEY
environment variable to complete the setup.
If you're using an on-premise version of GitGuardian, you also need to set the GITGUARDIAN_INSTANCE
environment variable with your on-premise instance URL (eg: https://dashboard.gitguardian.mycorp.local
).
#
Step 3: Scan your first content with ggshieldYou can scan one of your repositories for secrets with the following command:
ggshield secret scan repo /path/to/your/repo
You can also run ggshield -h
to get help on the CLI.
#
Go further with ggshieldIf you are looking to configure a CI/CD integration, take a look at our CI/CD Integrations page.
If you are looking to use GitGuardian at the git hooks level (pre-commit, pre-receive), take a look at our Git hooks documentation page.