{"id":6370,"library":"ggshield","title":"GitGuardian ggshield","description":"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.","status":"active","version":"1.49.0","language":"en","source_language":"en","source_url":"https://github.com/GitGuardian/ggshield","tags":["security","secrets detection","CLI","devsecops","git-hooks"],"install":[{"cmd":"pip install ggshield","lang":"bash","label":"Standard pip installation (isolated environment with pipx recommended)"},{"cmd":"pipx install ggshield","lang":"bash","label":"Recommended for isolated environment"}],"dependencies":[{"reason":"Requires Python >=3.9","package":"Python","optional":false},{"reason":"Required for repository and hook scanning functionalities (not for standalone packages)","package":"Git","optional":false}],"imports":[{"note":"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`.","symbol":"ggshield","correct":"import subprocess\nsubprocess.run(['ggshield', '--version'])"}],"quickstart":{"code":"import os\nimport subprocess\n\n# --- Step 1: Authenticate ---\n# The recommended way is to run 'ggshield auth login' interactively in your terminal.\n# This example assumes you've already authenticated or set GITGUARDIAN_API_KEY.\n# For CI/CD, set the GITGUARDIAN_API_KEY environment variable.\n# Example: export GITGUARDIAN_API_KEY=\"your_gitguardian_api_key_here\"\n\n# Simulate a file with a potential secret for scanning\nwith open('temp_secret_file.txt', 'w') as f:\n    f.write('This is some test content.\\n')\n    f.write('API_KEY=ghs_test_this_is_a_fake_api_key_1234567890abcdef')\n\nprint(\"\\n--- Running ggshield secret scan path on temp_secret_file.txt ---\")\ntry:\n    # Scan a specific file\n    result = subprocess.run(\n        ['ggshield', 'secret', 'scan', 'path', 'temp_secret_file.txt'],\n        capture_output=True, text=True, check=False\n    )\n    print(\"Scan Output:\\n\", result.stdout)\n    if result.stderr:\n        print(\"Scan Errors:\\n\", result.stderr)\n    if result.returncode != 0:\n        print(\"Secret(s) detected or scan failed. Exit code:\", result.returncode)\n    else:\n        print(\"No secrets detected.\")\nexcept FileNotFoundError:\n    print(\"Error: 'ggshield' command not found. Please ensure ggshield is installed and in your PATH.\")\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up the temporary file\n    if os.path.exists('temp_secret_file.txt'):\n        os.remove('temp_secret_file.txt')\n","lang":"python","description":"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."},"warnings":[{"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).","message":"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.","severity":"breaking","affected_versions":">=1.49.0"},{"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.","message":"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.","severity":"deprecated","affected_versions":">=1.44.1"},{"fix":"Use `pipx install ggshield` for initial installation and `pipx upgrade ggshield` for updates. Ensure `pipx` is installed (`pip install pipx && pipx ensurepath`).","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Add `.cache_ggshield/` to your project's `.gitignore` file to prevent it from being tracked.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-15T00:00:00.000Z","next_check":"2026-07-14T00:00:00.000Z"}