$ show GitGuardian/ggshield
ggshield is a production-grade CLI tool for detecting hardcoded secrets in code, git history, Docker images, PyPI packages, archives, and AI coding assistant interactions. It integrates with the GitGuardian API to scan for 500+ secret types, supporting both SaaS and self-hosted instances. The tool is designed for developers and CI/CD pipelines, offering git hooks (pre-commit, pre-push, pre-receive), a plugin system for extensibility, and AI agent hooks for Claude Code, Cursor, Copilot, Codex, Vibe, and Kiro. It also includes HMSL (Has My Secret Leaked) for checking secret exposure via cryptographic queries, honeytoken management, and machine-level setup for comprehensive security coverage. The architecture is a hybrid Python/Rust CLI built with Click. The Python codebase is organized into three layers: `cmd` (CLI commands), `core` (shared infrastructure like config, scan, cache, client, UI, plugin system), and `verticals` (domain logic for secret scanning, AI, HMSL, honeytokens). A Rust native component (`ggshield-hook`) handles AI hook scanning for performance, while a Rust dispatcher delegates non-hook commands to the Python launcher. The plugin system supports dynamic command registration with sigstore signature verification. Configuration is YAML-based with versioned schemas and global/local merging. Key entry points include `ggshield/__main__.py` (CLI root), `ggshield/cmd/secret/scan/` (scan subcommands), `ggshield/cmd/auth/login.py` (authentication), `ggshield/cmd/machine/setup.py` (one-shot protection), and `rust/dispatcher/src/main.rs` (Rust binary). External dependencies include the GitGuardian API (py-gitguardian), keyring for credential storage, and platform-specific utilities for notifications and machine ID derivation. The codebase demonstrates strong engineering practices with lazy command loading, output handler strategy pattern, cache abstractions, and comprehensive test coverage (80%+).
The LLM identified 5 files worth highlighting for reuse:
Defines the abstract `GGShieldUI` base class that provides a consistent interface for user interaction (display, progress, logging, confirmation). It is implemented by `PlainTextGGShieldUI` and `RichGGShieldUI`, allowing the CLI to switch between plain text and rich terminal output without changing business logic. This pattern is reusable in any CLI tool that needs multiple output formats.
Defines the `ScanMode` enum with all supported scan modes (repo, path, commit, pre-commit, pre-push, pre-receive, ci, docker, pypi, archive, docset, ai_hook). This simple but well-structured enum centralizes scan mode definitions and is used throughout the codebase for dispatch and configuration. It demonstrates clean separation of concerns and is easily extensible.
Implements cryptographic operations for the HMSL (Has My Secret Leaked) subsystem, including SHA-256 hashing, AES-GCM encryption/decryption, and key derivation. These operations are used to query the GitGuardian API for secret exposure without revealing the actual secret. The module is self-contained, uses standard library and pycryptodome, and can be extracted for any project needing secure hash-based lookup.
Provides a comprehensive set of git command wrappers with robust error handling, caching, path resolution, and macOS CLT stub detection. Functions like `check_git_dir`, `get_filepaths_from_ref`, `get_staged_filepaths`, and `is_gitignored` are used across scanning, installation, and CI integration. This module is reusable in any Python project that needs to interact with git repositories programmatically.
Implements wheel signature verification using Sigstore bundles. It verifies signatures against a vendored trusted root, supports STRICT/WARN/DISABLED modes, and handles both bundled and detached signatures. This module demonstrates non-obvious skill in supply-chain security and can be extracted for any Python project that needs to verify plugin or package signatures.