pygitguardian

Warnings

• breaking Version 1.20.0 removed support for the deprecated SCA (Software Composition Analysis) and IaC (Infrastructure as Code) scanning endpoints.
  Fix: Migrate any code using these deprecated endpoints to alternative GitGuardian API methods or tools, or ensure your application does not rely on these specific functionalities.
• breaking Version 1.25.0 updated the `Client.scan_and_create_incidents()` method to align with server-side API changes. This may require reviewing and updating parameters or expected behavior if this method was previously used.
  Fix: Consult the latest pygitguardian documentation or examples for `scan_and_create_incidents()` to ensure correct usage with the updated API.
• gotcha In version 1.27.0, several fields including `visibility`, `kind`, `presence status`, `ignore_reason`, and `tag` were changed to `str` type. Code expecting different types (e.g., enums or custom objects) might encounter type errors.
  Fix: Update type hints and any logic that processes these fields to expect string values. Perform explicit type conversions if a non-string type is required by your application.
• gotcha As of version 1.23.0, the `detector_name` and `detector_group_name` fields in `PolicyBreak` objects were made optional. Code expecting these fields to always be present should implement checks for `None`.
  Fix: Before accessing `policy_break.detector_name` or `policy_break.detector_group_name`, check if the value is `None` to prevent `AttributeError` or unexpected behavior.

Install

• pip install pygitguardian Install stable version

Imports

• GGClient

  from pygitguardian import GGClient

  The primary client for interacting with the GitGuardian API.
• Detail

  from pygitguardian.models import Detail

  A model used for handling API response details, such as error messages.

Quickstart

Initializes the GGClient with an API key sourced from an environment variable and performs a content scan for secrets. It includes a health check and prints detected incidents. API keys should always be handled securely, ideally via environment variables, to prevent exposure.

import os
from pygitguardian import GGClient
from pygitguardian.models import ScanResult

# It is highly recommended to use environment variables for API keys.
# Replace 'YOUR_GITGUARDIAN_API_KEY' with your actual environment variable name if different.
api_key = os.environ.get('GITGUARDIAN_API_KEY', '')

if not api_key:
    print("Error: GITGUARDIAN_API_KEY environment variable not set.")
    exit(1)

client = GGClient(api_key=api_key)

document_to_scan = """ 
This is some example content.
It might contain sensitive information like a password: mysecretpassword123
or an API key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
"""

try:
    # Check the health of the API and the API key used first
    health_check_result = client.health_check()
    if not health_check_result.success:
        print(f"API Health Check failed: {health_check_result.detail}")
        exit(1)
    print("API Health Check successful.")

    scan_result: ScanResult = client.content_scan(document_to_scan)

    if scan_result.has_secrets:
        print("Secrets found in the document!")
        for incident in scan_result.incidents:
            print(f"  Incident type: {incident.type}")
            for pb in incident.policy_breaks:
                print(f"    Policy Break: {pb.occurrence.value}")
    else:
        print("No secrets found in the document.")

except Exception as e:
    print(f"An error occurred during scan: {e}")