GitGuardian SDKs & Libraries: Python, Go, Node.js (2026)

SDKs overview

GitGuardian provides software development kits (SDKs) and command-line interfaces (CLIs) to facilitate the integration of its secrets detection capabilities into development workflows. While GitGuardian's core functionality operates by scanning code for various types of sensitive information, including API keys, database credentials, and certificates, the SDKs and CLIs enable developers to perform scans locally, integrate with version control systems, and embed security checks directly into continuous integration and continuous deployment (CI/CD) pipelines. This approach is consistent with shift-left security principles, aiming to identify and remediate vulnerabilities earlier in the development lifecycle Google Cloud DevSecOps guide.

The primary tool for interacting with GitGuardian's detection engine programmatically is the ggshield CLI, which offers functionalities for scanning repositories, files, and directories. Beyond the CLI, GitGuardian offers official libraries for common programming languages, allowing for more granular control and custom integrations with existing codebases and development tools. These tools support GitGuardian's core products, including Internal Monitoring for private repositories and Public Monitoring for public-facing codebases GitGuardian documentation portal.

Official SDKs by language

GitGuardian maintains official SDKs and a CLI tool engineered to integrate secrets detection directly into development processes. The primary official offering is the ggshield CLI, which is a Go-based application providing a uniform interface across different environments. In addition to the CLI, GitGuardian provides official libraries for common programming languages, enabling developers to build custom integrations or incorporate secrets scanning into applications.

The following table outlines the key official tools provided by GitGuardian:

These official SDKs and tools are designed to streamline the adoption of GitGuardian's security capabilities, providing developers with the means to embed security checks at various stages of their development pipeline GitGuardian's developer documentation.

Installation

The installation process for GitGuardian's primary CLI tool, ggshield, varies slightly depending on the operating system. For Python and Node.js SDKs, standard package managers are used. Before installation, users should ensure they have obtained a GitGuardian API key, which is required for authentication with the GitGuardian API GitGuardian Getting Started guide.

Installing ggshield CLI

ggshield can be installed via various methods, including package managers, direct download, or as a Docker image. The recommended method typically depends on the user's environment.

Using Homebrew (macOS/Linux):

brew tap gitguardian/homebrew-ggshield
brew install ggshield

Using pip (Python):

While ggshield is primarily a Go application, a Python wrapper is available for environments where pip is preferred or necessary:

pip install ggshield

Direct Download:

Pre-compiled binaries for various operating systems (Linux, Windows, macOS) are available for direct download from the GitGuardian GitHub releases page ggshield installation instructions. After downloading, the binary typically needs to be placed in a directory included in the system's PATH.

Docker:

For containerized environments or CI/CD pipelines, ggshield can be run directly from a Docker image:

docker pull gitguardian/ggshield

Installing Python SDK (py-gitguardian)

pip install py-gitguardian

Installing Node.js SDK (@gitguardian/api-client)

npm install @gitguardian/api-client
# or
yarn add @gitguardian/api-client

After installation, users typically need to configure ggshield with their GitGuardian API key using the command ggshield auth login or by setting the GITGUARDIAN_API_KEY environment variable GitGuardian authentication guide.

Quickstart example

This quickstart demonstrates how to use the ggshield CLI to scan a local Git repository for secrets before pushing changes. This is a common use case for developers to catch secrets early in their workflow.

Prerequisites:

• ggshield CLI installed and authenticated with a GitGuardian API key.
• A local Git repository.

Step-by-step example:

1. Navigate to your repository:

   cd my-git-repo
   

2. Add a file with a simulated secret:

   Create a file named config.py with some content simulating a secret. For this example, we'll use a placeholder secret.

   # config.py
   API_KEY = "sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
   DATABASE_URL = "postgresql://user:password@host:5432/dbname"
   

3. Stage the file:

   git add config.py
   

4. Run ggshield scan on staged changes:

   Use the scan pre-push command to simulate a pre-push hook scan, or scan path . to scan the entire current directory. The --staged flag is useful for scanning only changes that are about to be committed.

   ggshield scan pre-push
   

   Alternatively, to scan the entire project directory:

   ggshield scan path .
   

   If secrets are detected, ggshield will output a report detailing the findings, including the type of secret, the file path, and the exact line number. It will also return a non-zero exit code, which can be used to block Git operations in CI/CD pipelines or pre-commit hooks.

   Example output (abbreviated):

   [+] Scanning content of 1 commit...
     [...] 
     secret detected: API Key
       File: config.py
       Line: 2
       Match: sk_live_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
     secret detected: Database Connection String
       File: config.py
       Line: 3
       Match: postgresql://user:password@host:5432/dbname
   
   ERROR: 2 incidents detected. Some secrets have been found. 
   

5. Remediate the secret (if detected):

   If secrets are found, remove them from the code, commit the cleaned version, and then try scanning or pushing again. For a persistent solution, consider using environment variables, a secrets manager, or an infrastructure-as-code tool to inject sensitive data at runtime GitGuardian remediation guidelines.

This quickstart demonstrates the immediate feedback loop ggshield provides, allowing developers to address security issues before they become part of the codebase history.

Community libraries

While GitGuardian provides official SDKs and a CLI, the open-source nature of many development communities often leads to the creation of unofficial, community-contributed libraries and integrations. These libraries can extend GitGuardian's functionality to languages not officially supported, or provide specialized integrations for niche tools and platforms.

Community contributions can include:

• Language-specific wrappers: SDKs for languages like Ruby, PHP, or Java, which might wrap the GitGuardian API for easier use within those ecosystems.
• Editor/IDE plugins: Integrations that provide real-time secrets detection feedback directly within development environments such as VS Code or IntelliJ IDEA.
• CI/CD pipeline extensions: Custom actions or orb packages for platforms like GitHub Actions, GitLab CI, or CircleCI, offering alternative ways to integrate ggshield beyond the official documentation.
• Framework-specific integrations: Libraries designed to work with particular web frameworks (e.g., Django, Ruby on Rails, Spring Boot) to ensure secrets are handled securely within those contexts.

Developers seeking community libraries are encouraged to explore platforms like GitHub, PyPI, npm, or RubyGems, using search terms such as "GitGuardian" combined with their desired language or tool. It is important to note that community-maintained projects may vary in terms of stability, support, and adherence to security best practices. Users should always review the source code and community activity before incorporating such libraries into production systems. GitGuardian's official documentation and community forums may also list or link to notable community projects GitGuardian documentation.

For example, projects that aim to integrate into various CI/CD pipelines might leverage generic webhook capabilities Twilio's webhook security guide to report findings, which could be implemented in any language with HTTP client capabilities.