GitGuardian ggshield

Warnings

• breaking Pre-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).
• deprecated The `--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.
• gotcha It 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`).
• gotcha The `.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.
• gotcha Authentication 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.

Install

• pip install ggshield Standard pip installation (isolated environment with pipx recommended)
• pipx install ggshield Recommended for isolated environment

Imports

• ggshield

  import subprocess
  subprocess.run(['ggshield', '--version'])

  ggshield is primarily a CLI tool; its core scanning functionality is accessed via command-line execution, not direct Python imports for programmatic use. For automation, use `subprocess`.

Quickstart

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')