gitguardian/ggshieldDetecta 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](https://github.com/GitGuardian/ggshield): protege tu código con GitGuardian
[](https://pypi.org/project/ggshield/)
[](https://hub.docker.com/r/gitguardian/ggshield)
[](LICENSE)
[](https://github.com/GitGuardian/ggshield/stargazers)
[](https://github.com/GitGuardian/ggshield/actions)
[](https://codecov.io/gh/GitGuardian/ggshield/)
> [!IMPORTANT]
> **macOS: actualizar a la versión 1.54.0 activa una solicitud del Llavero para `ggshield-py`**, un segundo binario que ahora lee tu token guardado como parte de nuestras mejoras de rendimiento. Haz clic en **Permitir siempre**; no volverá a preguntar.
`ggshield` es una aplicación CLI que se ejecuta en tu entorno local o en un entorno de CI para ayudarte a detectar más de 500 tipos de secretos.
`ggshield` utiliza nuestra [API pública](https://api.gitguardian.com/docs) a través de [py-gitguardian](https://github.com/GitGuardian/py-gitguardian) para escanear y detectar posibles vulnerabilidades en archivos y otros contenidos de texto.
De los escaneos realizados con `ggshield` solo se almacenan metadatos como la hora de la llamada, el tamaño de la solicitud y el modo de escaneo, por lo que los secretos no se mostrarán en tu panel y **tus archivos y secretos no se almacenarán**.
# Tabla de contenidos
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
- [Instalación](#instalación)
- [Script de instalación (Recomendado)](#script-de-instalación-recomendado)
- [macOS](#macos)
- [Homebrew](#homebrew)
- [Paquete .pkg independiente](#paquete-pkg-independiente)
- [Linux](#linux)
- [Paquetes Deb y RPM](#paquetes-deb-y-rpm)
- [Windows](#windows)
- [Chocolatey](#chocolatey)
- [Instalador MSI](#instalador-msi)
- [Archivo .zip independiente](#archivo-zip-independiente)
- [Todos los sistemas operativos](#todos-los-sistemas-operativos)
- [Usando pipx](#usando-pipx)
- [Usando pip](#usando-pip)
- [Configuración inicial](#configuración-inicial)
- [Usando `ggshield auth login`](#usando-ggshield-auth-login)
- [Configuración manual](#configuración-manual)
- [Primeros pasos](#primeros-pasos)
- [Secretos](#secretos)
- [Migrar un archivo de configuración heredado](#migrar-un-archivo-de-configuración-heredado)
- [Integraciones](#integraciones)
- [Asistentes de codificación con IA](#asistentes-de-codificación-con-ia)
- [Más información](#más-información)
- [Salida](#salida)
- [Proyectos de código abierto relacionados](#proyectos-de-código-abierto-relacionados)
- [Licencia](#licencia)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
# Instalación
<!--
Any change made in this section must be replicated in the "Step 1: Install
ggshield" section of the "Getting started" page of ggshield public
documentation.
-->
## Script de instalación (Recomendado)
La forma más rápida de instalar `ggshield`.
Linux / macOS:
```shell
curl -sSfL \
https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.sh | bash
```
Windows (PowerShell):
```powershell
irm https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | iex
```
O, si prefieres `curl` (incluido con Windows 10+):
```powershell
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` (instalar 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`](https://github.com/gitguardian/ggshield/blob/main/scripts/install/README.md) para ver la lista completa
de opciones, los demás métodos de instalación y cómo desinstalar.
Los métodos siguientes instalan la CLI manualmente en su lugar.
## macOS
### Homebrew
Puedes instalar `ggshield` usando Homebrew:
```shell
brew install ggshield
```
La actualización la gestiona Homebrew.
### Paquete .pkg independiente
Como alternativa, puedes descargar e instalar un paquete .pkg independiente desde la [página de versiones de `ggshield`](https://github.com/GitGuardian/ggshield/releases).
Este paquete _no_ requiere instalar Python, pero tendrás que descargar manualmente las nuevas versiones.
## Linux
### Paquetes Deb y RPM
Los paquetes Deb y RPM están disponibles en [Cloudsmith](https://cloudsmith.io/~gitguardian/repos/ggshield/packages/).
Instrucciones de configuración:
- [Paquetes Deb](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-deb)
- [Paquetes RPM](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-rpm)
La actualización la gestiona el gestor de paquetes.
## Windows
### Chocolatey
`ggshield` está disponible a través del [gestor de paquetes Chocolatey](https://chocolatey.org/packages/ggshield):
```shell
choco install ggshield
```
### Instalador MSI
Descarga el instalador MSI desde la [página de versiones de `ggshield`](https://github.com/GitGuardian/ggshield/releases) e instálalo:
```powershell
msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi
```
### Archivo .zip independiente
Proporcionamos un archivo .zip independiente en la [página de versiones de `ggshield`](https://github.com/GitGuardian/ggshield/releases).
Descomprime el archivo en tu disco y, a continuación, añade el directorio que contiene el archivo `ggshield.exe` a `%PATH%`.
Este archivo _no_ requiere instalar Python, pero tendrás que 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 de PyPI](https://pypi.org/project/ggshield).
Requiere **una versión compatible de Python (no EOL)** (excepto para los paquetes independientes) y git.
Si no utilizas nuestras versiones empaquetadas de `ggshield`, ten en cuenta que seguimos el [ciclo de versiones de Python](https://devguide.python.org/versions/) y no damos soporte a las versiones que han alcanzado el EOL.
### Usando pipx
La forma recomendada de instalar `ggshield` desde PyPI es usar [pipx](https://pypa.github.io/pipx/), que lo instalará en un entorno aislado:
```shell
pipx install ggshield
```
Para actualizar tu instalación, ejecuta:
```shell
pipx upgrade ggshield
```
### Usando pip
También puedes instalar `ggshield` desde PyPI usando pip, pero no es recomendable porque la instalación no está aislada, por lo que otras aplicaciones o paquetes instalados de esta forma pueden afectar a tu instalación de `ggshield`. Este método tampoco funcionará si tu instalación de Python está declarada como gestionada externamente (por ejemplo, al usar el Python del sistema en sistemas operativos como Debian 12):
```shell
pip install --user ggshield
```
Para actualizar tu instalación, ejecuta:
```shell
pip install --user --upgrade ggshield
```
# Configuración inicial
## Usando `ggshield auth login`
Para usar `ggshield` necesitas autenticarte contra los servidores de GitGuardian. Para ello, usa el comando `ggshield auth login`. Este comando automatiza el aprovisionamiento 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`](https://docs.gitguardian.com/internal-repositories-monitoring/ggshield/reference/auth/login).
Después de autenticarte, ejecuta `ggshield machine setup` para configurar los hooks de IA y de git,
plantar honeytokens y registrar la máquina en la página de Endpoints antes de su primer
escaneo. El registro incluye al usuario actual, o a todos los usuarios objetivo de honeytokens cuando
se ejecuta como root. Es de mejor esfuerzo, tarda como máximo cinco segundos y no afecta
al código de salida del comando.
Los escaneos de `ggshield secret scan pre-commit`, `pre-push` y `ai-hook` también envían
el nombre de host de la máquina, a partir del cual GitGuardian registra a los usuarios de estos hooks.
Otros comandos de escaneo no lo envían, ni tampoco lo hace el hook de IA nativo que ejecutan las instalaciones
independientes y específicas de plataforma de `pip`.
En CI, ggshield no registra la máquina ni envía el nombre de host. Para desactivar ambos
en otros entornos, establece `endpoint_registration: false` en `.gitguardian.yaml`, o establece
`GGSHIELD_NO_ENDPOINT_REGISTRATION` con un valor no vacío.
## 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 de Docker (el comando `docker` debe estar disponible): `ggshield secret scan docker ubuntu:22.04`
- en paquetes de Pypi (el comando `pip` debe estar disponible): `ggshield secret scan pypi flask`
- y más, consulta la salida de `ggshield secret scan --help` para obtener más detalles.
## Migrar un archivo de configuración heredado
Si `ggshield` informa de que tu archivo de configuración `.gitguardian.yaml` (o `.gitguardian.yml`) usa un formato obsoleto, migrarlo a la última versión con:
```shell
ggshield config migrate
```
De forma predeterminada, esto 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, indica a `ggshield` la ruta del archivo explícitamente:
```shell
ggshield --config-path path/to/.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 de CI/CD](https://docs.gitguardian.com/ggshield-docs/integrations/overview#cicd-integrations-secrets-detection-in-your-cicd-workflow).
Para detectar errores antes, usa `ggshield` como [hook de Git pre-commit, pre-push o pre-receive](https://docs.gitguardian.com/ggshield-docs/integrations/overview#git-hooks-prevent-secrets-from-reaching-your-vcs).
## Asistentes de codificación con IA
`ggshield` puede [escanear interacciones](https://docs.gitguardian.com/ggshield-docs/integrations/ai-coding-tools/secret-scanning-for-ai-coding-tools) entre tú y tu asistente de codificación con IA en tiempo real, bloqueando las acciones que contienen secretos antes de que se ejecuten.
Puedes instalar los hooks con el comando `ggshield install`.
Herramientas compatibles: **Cursor**, **Claude Code**, **Copilot Chat**, **Codex** y
**Mistral Vibe 2.21+**.
# Más información
Para obtener más información, consulta [la documentación](https://docs.gitguardian.com/ggshield-docs/getting-started)
# Salida
Si no se ha encontrado ningún secreto, el código de salida será 0:
```bash
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 indicará el nombre del archivo donde se ha encontrado el secreto y un parche que te mostrará la posición del secreto en el archivo:
```shell
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 demasiado largas se truncan para ajustarse al tamaño del terminal, a menos que se use el modo detallado (`-v` o `--verbose`).
# Proyectos de código abierto relacionados
- [truffleHog](https://github.com/dxa4481/truffleHog)
- [gitleaks](https://github.com/zricethezav/gitleaks)
- [gitrob](https://github.com/michenriksen/gitrob)
- [git-hound](https://github.com/tillson/git-hound)
- [AWS git-secrets](https://github.com/awslabs/git-secrets)
- [detect-secrets](https://github.com/Yelp/detect-secrets)
# Licencia
`ggshield` tiene licencia MIT.