Registry / auth-security / ggshield

ggshield

JSON →
library1.51.0pypypi✓ verified 84d ago

ggshield is a CLI application that runs in your local environment or in a CI environment to detect over 500 types of secrets, as well as other potential security vulnerabilities or policy breaks. It uses the GitGuardian public API through `py-gitguardian` for scanning. The current version is 1.49.0, with frequent releases addressing new features and fixes.

pip install ggshield
INSTALL
IMPORT
SIG · GGSHIELD
G
ggshield
auth-securitypythonv1.51.0
Install
9.8s avg
Import
15ms
Disk
89MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v1.51.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.920 runs
installs and imports cleanly · install 0.0s · import 0.016s · 85MB
glibc
py 3.103.920 runs
installs and imports cleanly · install 9.8s · import 0.014s · 85MB
89MB installed
● package 89MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

ggshield
import ggshield
import subprocess

This quickstart demonstrates how to run a basic secret scan using `ggshield` via Python's `subprocess` module. It creates a temporary file with a simulated secret, scans it, and prints the output. Prior to running, you must authenticate `ggshield` by either running `ggshield auth login` in your terminal or by setting the `GITGUARDIAN_API_KEY` environment variable for non-interactive environments like CI/CD.

import os import subprocess # --- Step 1: Authenticate --- # The recommended way is to run 'ggshield auth login' interactively in your terminal. # This example assumes you've already authenticated or set GITGUARDIAN_API_KEY. # For CI/CD, set the GITGUARDIAN_API_KEY environment variable. # Example: export GITGUARDIAN_API_KEY="your_gitguardian_api_key_here" # Simulate a file with a potential secret for scanning with open('temp_secret_file.txt', 'w') as f: f.write('This is some test content.\n') f.write('API_KEY=ghs_test_this_is_a_fake_api_key_1234567890abcdef') print("\n--- Running ggshield secret scan path on temp_secret_file.txt ---") try: # Scan a specific file result = subprocess.run( ['ggshield', 'secret', 'scan', 'path', 'temp_secret_file.txt'], capture_output=True, text=True, check=False ) print("Scan Output:\n", result.stdout) if result.stderr: print("Scan Errors:\n", result.stderr) if result.returncode != 0: print("Secret(s) detected or scan failed. Exit code:", result.returncode) else: print("No secrets detected.") except FileNotFoundError: print("Error: 'ggshield' command not found. Please ensure ggshield is installed and in your PATH.") except Exception as e: print(f"An error occurred: {e}") finally: # Clean up the temporary file if os.path.exists('temp_secret_file.txt'): os.remove('temp_secret_file.txt')
ggshield --version
Debug
Known issues
breakingPre-receive hook support for GitHub Enterprise Server versions v3.9 to v3.13 was removed in v1.49.0. These versions are EOL, and users on these platforms should upgrade GitHub Enterprise Server to continue using pre-receive hooks or consider alternative integration methods.
fix
Upgrade your GitHub Enterprise Server instance to a supported version, or migrate to a different `ggshield` integration (e.g., GitHub Actions, pre-commit hooks).
affects: >=1.49.0
deprecatedThe `--allow-self-signed` CLI option and `allow_self_signed` configuration setting are deprecated in favor of `--insecure` and `insecure: true`. Using these options disables SSL verification, making connections vulnerable to Man-in-the-Middle (MITM) attacks. It is strongly recommended to install self-signed certificates into your system's trust store, especially with Python 3.10+ which automatically uses it.
fix
Prefer installing your self-signed certificates into your system's trust store. If absolutely necessary, use `--insecure` or `insecure: true` but be aware of the security risks involved.
affects: >=1.44.1
gotchaIt is highly recommended to install `ggshield` using `pipx` for an isolated environment. Using `pip install --user ggshield` is not recommended as it can lead to conflicts with other Python packages or issues with externally managed Python installations.
fix
Use `pipx install ggshield` for initial installation and `pipx upgrade ggshield` for updates. Ensure `pipx` is installed (`pip install pipx && pipx ensurepath`).
affects: All
gotchaThe `.cache_ggshield` directory created by `ggshield` for caching should always be ignored in your Git repository (e.g., by adding it to `.gitignore`). Not doing so can lead to unexpected behavior or unnecessary commits.
fix
Add `.cache_ggshield/` to your project's `.gitignore` file to prevent it from being tracked.
affects: All
gotchaAuthentication is mandatory for `ggshield` to function. The CLI requires an API key, either configured via `ggshield auth login` (recommended for local workstations) or by setting the `GITGUARDIAN_API_KEY` environment variable. A clear error message is now provided if the token is missing.
fix
Run `ggshield auth login` to authenticate interactively, or set the `GITGUARDIAN_API_KEY` environment variable with your GitGuardian API key, especially in CI/CD environments.
affects: All
Upgrade
Version history
1.51.0latest on PyPI · released May 26, 2026
Audit
Dependencies
PythonrequiredRequires Python >=3.9
GitrequiredRequired for repository and hook scanning functionalities (not for standalone packages)
Agent activity
20 hits · last 30 days
node
20
Resources
ggshield — pip install ggshield · libregistry