py-gitguardian - GitGuardian API Client

GitHub Workflow Status

API client library for the GitGuardian API.

The GitGuardian API puts at your fingertips the power to detect more than 200 types of secrets in any text content, as well as other potential security vulnerabilities.

py-gitguardian can be used to create integrations to scan various data sources, from your workstation's filesystem to your favorite chat application.

You can check API details here with all the response codes and expected structures on each method.

Requirements

Python 3.9+

Projects using `py-gitguardian`

GitGuardian Shield - Scan for secrets in your CI and pre-commit.

Getting started

You can obtain API keys for API usage on your dashboard.

pip

pip3 install --upgrade pygitguardian

pipenv

pipenv install pygitguardian

pdm

pdm add pygitguardian

poetry

poetry add pygitguardian

Examples

Check examples/ for full examples on how to use py-gitguardian.

Scanning text content

# please don't hardcode your gg_api_key in source code :)
API_KEY = os.getenv("GITGUARDIAN_API_KEY")
DOCUMENT = """
    import urllib.request
    url = 'http://jen_barber:correcthorsebatterystaple@cake.gitguardian.com/isreal.json'
    response = urllib.request.urlopen(url)
    consume(response.read())"
"""

client = GGClient(api_key=API_KEY)

# Check the health of the API and the API key used.
if client.health_check().success:
    try:
        scan_result = client.content_scan(DOCUMENT)
    except Exception as exc:
        # Handle exceptions such as schema validation
        traceback.print_exc(2, file=sys.stderr)
        print(str(exc))
        print(scan_result)
else:
    print("Invalid API Key")

Scanning multiple files

API_KEY = os.getenv("GITGUARDIAN_API_KEY")
client = GGClient(api_key=API_KEY)

# Create a list of dictionaries for scanning
file_paths = (pathlib.Path(name) for name in glob.iglob("**/*", recursive=True))
to_scan = [
    {"filename": path.name, "document": path.read_text(errors="replace")}
    for path in file_paths
]

scan = client.multi_content_scan(to_scan)

Transform results to dict or JSON

Any model in py-gitguardian can be turned to a JSON string or a dictionary using the to_dict and to_json methods.

from pygitguardian.models import Detail

detail = Detail("Invalid API Key.")
print(detail.to_dict())
print(detail.to_json())

Dependencies

Py-gitguardian depends on these excellent libraries:

requests - HTTP client
marshmallow - Request (de)serialization and input validation

Metadata

Release files for pygitguardian 1.35.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pygitguardian 1.35.0
File	Size	Uploaded
pygitguardian-1.35.0.tar.gz	64.3 kB	Sep 22, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for pygitguardian 1.35.0
File	Interpreter	ABI	Platform	Reset
pygitguardian-1.35.0-py3-none-any.whl 24.8 kB Sep 22, 2026	Python 3	none	any	Details

Total release size: 89.1 kB

Release files / pygitguardian-1.35.0.tar.gz

Download URL	pygitguardian-1.35.0.tar.gz
Size	64.3 kB
Tags	Source
SHA-256 checksum How to use checksums	`e9af79fe66cfd5e8063fc140cdaac95b987949ba1dc96941bb27b53ae2b8bc38`
BLAKE2b-256 checksum How to use checksums	`e36a2ff0e9a42bf6ef3a11bf0d9b2d53bc0bb3ca84531ef4435d856c187d10fe`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Release files / pygitguardian-1.35.0-py3-none-any.whl

Download URL	pygitguardian-1.35.0-py3-none-any.whl
Size	24.8 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`8c9969fc9aaf0e8b5d9c9ef8289e779393ad3b9fc64ff686643eedbda3eb70b6`
BLAKE2b-256 checksum How to use checksums	`25efddf02561c69263558377ddf8cd607a014905588fb28d744cb1684b38b396`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.13.14`