ggshield v1.54.0-rc1
Detecta y valida más de 500 tipos de secretos codificados con comprobaciones avanzadas. Úsalo como un enlace de pre-commit, acción de GitHub o CLI para la detección y seguridad proactiva de secretos.
ggshield: protege tu código con GitGuardian
ggshield es una aplicación CLI que se ejecuta en tu entorno local o en un entorno CI para ayudarte a detectar más de 500 tipos de secretos.
ggshield utiliza nuestra API pública a través de py-gitguardian para escanear y detectar vulnerabilidades potenciales en archivos y otro contenido de texto.
Solo se almacenan metadatos como la hora de la solicitud, el tamaño de la solicitud y el modo de escaneo de los escaneos que usan ggshield, por lo tanto, los secretos no se mostrarán en tu panel de control y tus archivos y secretos no se almacenarán.
Índice
- Instalación
- Configuración inicial
- Primeros pasos
- Integraciones
- Aprende más
- Salida
- Proyectos de código abierto relacionados
- Licencia
Instalación
Script de instalación (Recomendado)
La forma más rápida de instalar ggshield.
Linux / macOS:
curl -sSfL \
https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.sh | bash
Windows (PowerShell):
irm https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | iex
O, si prefieres curl (incluido con Windows 10+):
curl.exe -sSL https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | powershell -NoProfile -ExecutionPolicy Bypass -Command -
El script acepta opciones como --instance y --plugin (instala un plugin). Para el espacio de trabajo de la UE o una instancia autoalojada, establece la variable de entorno GITGUARDIAN_INSTANCE (o pasa --instance <URL>) antes de ejecutarlo.
Consulta scripts/install/README.md para obtener la lista completa de opciones, otros métodos de instalación y cómo desinstalar.
Los métodos siguientes instalan la CLI manualmente.
macOS
Homebrew
Puedes instalar ggshield usando Homebrew:
brew install ggshield
La actualización la gestiona Homebrew.
Paquete .pkg independiente
Alternativamente, puedes descargar e instalar un paquete .pkg independiente desde la página de lanzamiento de ggshield.
Este paquete no requiere instalar Python, pero debes descargar manualmente las nuevas versiones.
Linux
Paquetes Deb y RPM
Los paquetes Deb y RPM están disponibles en Cloudsmith.
Instrucciones de configuración:
La actualización la gestiona el gestor de paquetes.
Windows
Chocolatey
ggshield está disponible a través del gestor de paquetes Chocolatey:
choco install ggshield
Instalador MSI
Descarga el instalador MSI desde la página de lanzamiento de ggshield e instálalo:
msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi
Archivo .zip independiente
Proporcionamos un archivo .zip independiente en la página de lanzamiento de ggshield.
Descomprime el archivo en tu disco y luego agrega el directorio que contiene el archivo ggshield.exe a %PATH%.
Este archivo no requiere instalar Python, pero debes descargar manualmente las nuevas versiones.
Todos los sistemas operativos
ggshield se puede instalar en todos los sistemas operativos compatibles a través de su paquete PyPI.
Requiere una versión compatible de Python (que no haya llegado al final de su vida útil) (excepto para paquetes independientes) y git.
Si no usas nuestras versiones empaquetadas de ggshield, ten en cuenta que seguimos el ciclo de lanzamiento de Python y no admitimos versiones que hayan llegado al final de su vida útil.
Usando pipx
La forma recomendada de instalar ggshield desde PyPI es usar pipx, que lo instalará en un entorno aislado:
pipx install ggshield
Para actualizar tu instalación, ejecuta:
pipx upgrade ggshield
Usando pip
También puedes instalar ggshield desde PyPI usando pip, pero no se recomienda porque la instalación no está aislada, por lo que otras aplicaciones o paquetes instalados de esta manera pueden afectar tu instalación de ggshield. Este método tampoco funcionará si tu instalación de Python está declarada como administrada externamente (por ejemplo, al usar el Python del sistema en sistemas operativos como Debian 12):
pip install --user ggshield
Para actualizar tu instalación, ejecuta:
pip install --user --upgrade ggshield
Configuración inicial
Usando ggshield auth login
Para usar ggshield necesitas autenticarte contra los servidores de GitGuardian. Para hacerlo, usa el comando ggshield auth login. Este comando automatiza la provisión de un token de acceso personal y su configuración en la estación de trabajo local.
Puedes obtener más información en la documentación de ggshield auth login.
Configuración manual
También puedes crear tu token de acceso personal manualmente y almacenarlo en la variable de entorno GITGUARDIAN_API_KEY para completar la configuración.
Primeros pasos
Secretos
Ahora puedes usar ggshield para buscar secretos:
- en archivos:
ggshield secret scan path -r . - en repositorios:
ggshield secret scan repo . - en imágenes Docker (el comando
dockerdebe estar disponible):ggshield secret scan docker ubuntu:22.04 - en paquetes Pypi (el comando
pipdebe estar disponible):ggshield secret scan pypi flask - y más, echa un vistazo a la salida de
ggshield secret scan --helppara más detalles.
Migrando un archivo de configuración heredado
Si ggshield informa que tu archivo de configuración .gitguardian.yaml (o .gitguardian.yml) utiliza un formato obsoleto, migra la configuración a la versión más reciente con:
ggshield config migrate
Por defecto, busca el archivo de configuración en el directorio actual, así que ejecútalo desde el directorio que contiene el archivo. Para ejecutarlo desde cualquier lugar, apunta a ggshield explícitamente al archivo:
ggshield --config-path ruta/al/.gitguardian.yaml config migrate
La versión anterior del archivo se conserva como copia de seguridad .old junto a él.
Integraciones
Puedes integrar ggshield en tu flujo de trabajo CI/CD.
Para detectar errores antes, usa ggshield como un gancho de Git pre-commit, pre-push o pre-receive.
Asistentes de codificación de IA
ggshield puede escanear interacciones entre tú y tu asistente de codificación de IA en tiempo real, bloqueando acciones que contengan secretos antes de que se ejecuten.
Puedes instalar los ganchos con el comando ggshield install.
Herramientas compatibles: Cursor, Claude Code, Copilot Chat y Codex.
Aprende más
Para obtener más información, echa un vistazo a la documentación
Salida
Si no se han encontrado secretos, el código de salida será 0:
ggshield secret scan pre-commit
Si se encuentra un secreto en tu código preparado o en tu CI, recibirás una alerta que te dará el nombre del archivo donde se ha encontrado el secreto y un parche que te da la posición del secreto en el archivo:
ggshield secret scan pre-commit
2 incidents have been found in file production.rb
11 | config.paperclip_defaults = {
12 | :s3_credentials => {
13 | :bucket => "XXX",
14 | :access_key_id => "XXXXXXXXXXXXXXXXXXXX",
|_____AWS Keys_____|
15 | :secret_access_key => "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
|_______________AWS Keys_______________|
16 | }
17 | }
Las líneas que son demasiado largas se truncan para coincidir con el tamaño del terminal, a menos que se use el modo verbose (-v o --verbose).
Proyectos de código abierto relacionados
Licencia
ggshield tiene licencia MIT.