Skill ggshield Scanner para OpenClaw

Descripción General del Skill ggshield Scanner de OpenClaw

El skill ggshield Scanner integra el potente motor de detección de secretos de GitGuardian en tu flujo de trabajo de OpenClaw. En lugar de memorizar los flags del CLI de ggshield y los formatos de salida, puedes pedirle a OpenClaw que escanee tu código en busca de secretos filtrados usando lenguaje natural.

ggshield detecta más de 500 tipos de secretos hardcodeados — claves API, credenciales de bases de datos, tokens de nube, claves privadas y más. El skill OpenClaw ggshield scanner envuelve estas capacidades en una interfaz conversacional, facilitando la ejecución de escaneos bajo demanda, la configuración de hooks pre-commit y la interpretación de resultados sin salir de tu flujo de desarrollo.

Flujo de trabajo típico:

1. Pide a OpenClaw que escanee tu proyecto en busca de filtraciones de secretos.
2. El agente ejecuta ggshield secret scan contra tu base de código o archivos específicos.
3. Los resultados se devuelven en un resumen legible que destaca los secretos detectados, sus tipos y ubicaciones — sin necesidad de analizar la salida cruda del CLI.

Ya sea que estés auditando un repositorio existente o añadiendo escaneo de secretos a tu proceso de desarrollo, este skill se encarga del trabajo pesado. Combínalo con el skill de 1Password para un flujo de trabajo completo de gestión de secretos.

Prerrequisitos para el Skill ggshield Scanner

Antes de instalar el skill ggshield Scanner, asegúrate de tener:

• OpenClaw instalado y ejecutándose (v1.0+)
• ggshield instalado — guía oficial de instalación
• Python 3.9+ (si instalas vía pip/pipx) o usa paquetes independientes
• Git instalado para escaneo de repositorios
• clawhub CLI instalado para gestión de skills — guía de instalación

Instala ggshield usando tu método preferido:

# macOS (Homebrew)
brew install gitguardian/tap/ggshield

# Todas las plataformas (pipx — recomendado)
pipx install ggshield

# Todas las plataformas (pip)
pip install --user ggshield

Verifica tu configuración:

ggshield --version

Cómo Instalar el Skill ggshield Scanner

Instala el skill ggshield Scanner con un solo comando:

npx clawhub@latest install ggshield-scanner

Para verificar la instalación:

clawhub list

Deberías ver ggshield-scanner en tu lista de skills instalados. El skill requiere que ggshield esté disponible en tu PATH.

Configuración del Skill ggshield Scanner

Autenticación con GitGuardian

El skill ggshield Scanner requiere una clave API de GitGuardian para la detección de secretos. Puedes autenticarte de dos formas:

Inicio de sesión interactivo (recomendado para desarrollo local):

ggshield auth login

Esto abre tu navegador y genera automáticamente un token de acceso personal (PAT).

Variable de entorno (recomendado para CI/CD):

export GITGUARDIAN_API_KEY="your-api-key-here"

Configuración de Variables de Entorno

| Variable | Requerida | Descripción | |----------|-----------|-------------| | GITGUARDIAN_API_KEY | Sí | Token de acceso personal de GitGuardian | | GITGUARDIAN_INSTANCE | No | URL de instancia GitGuardian on-premise |

Importante: Nunca hardcodees tu clave API en archivos de configuración. Usa variables de entorno o un gestor de secretos como 1Password o Bitwarden.

Configuración de Hook Pre-commit

Para interceptar secretos antes de que sean committeados:

# Instalar hook para el repositorio actual
ggshield install --mode local

# Instalar hook globalmente para todos los repositorios
ggshield install --mode global

Ejemplos de Uso del Skill ggshield Scanner

1. Escanear un Directorio de Proyecto

Tú: "Escanea mi directorio del proyecto en busca de secretos hardcodeados"

El agente ejecuta ggshield secret scan path -r . contra tu directorio de trabajo y devuelve un resumen de secretos detectados, incluyendo la ruta del archivo, número de línea y tipo de secreto. Si no se encuentran secretos, recibes un informe limpio confirmando que tu código es seguro.

2. Auditar el Historial del Repositorio Git

Tú: "Revisa todo mi historial de git en busca de secretos filtrados"

El agente ejecuta ggshield secret scan repo . para escanear todos los commits en tu repositorio. Esto es útil para auditar bases de código legacy o asegurar que secretos previamente committeados han sido rotados y eliminados correctamente.

3. Escanear una Imagen Docker Antes del Despliegue

Tú: "Escanea la imagen Docker nginx:latest en busca de secretos"

El agente ejecuta ggshield secret scan docker nginx:latest para inspeccionar todas las capas de la imagen Docker. Esto captura secretos que pueden haberse incorporado en imágenes de contenedores durante el proceso de construcción — una fuente común de filtraciones de credenciales en producción.

4. Configurar Protección Pre-commit

Tú: "Instala un hook pre-commit para bloquear secretos de ser committeados"

El agente ejecuta ggshield install --mode local para añadir un hook git pre-commit a tu repositorio. Cada commit futuro será escaneado automáticamente, y los commits que contengan secretos detectados serán bloqueados antes de llegar a tu repositorio.

Seguridad y Mejores Prácticas

Sigue estas directrices al usar el skill ggshield Scanner:

• Usa escaneos de solo lectura por defecto. El skill solo debe escanear e informar — evita la auto-remediación sin revisar cuidadosamente cada hallazgo.
• Revisa antes de confirmar. Cuando el agente sugiera eliminar o rotar un secreto detectado, verifica que el hallazgo sea un verdadero positivo antes de tomar acción.
• Rota los secretos expuestos inmediatamente. Si ggshield detecta un secreto real en el historial de tu repositorio, rota la credencial de inmediato — eliminar el commit no es suficiente.
• Habilita hooks pre-commit. La prevención es mejor que la detección. Configura hooks con ggshield install para capturar secretos antes de que entren al control de versiones.
• Mantén ggshield actualizado. Se añaden nuevos patrones de secretos regularmente. Ejecuta pipx upgrade ggshield o brew upgrade ggshield para mantenerte al día.

Solución de Errores Comunes

"Error: Invalid API key"

Tu clave API de GitGuardian falta o ha expirado. Re-autentícate con ggshield auth login o verifica que tu variable de entorno GITGUARDIAN_API_KEY esté configurada correctamente. Comprueba que el token no haya sido revocado en el panel de GitGuardian.

"Error: ggshield command not found"

ggshield no está instalado o no está en tu PATH. Instálalo con pipx install ggshield o brew install gitguardian/tap/ggshield. Si lo instalaste vía pip, asegúrate de que el directorio de scripts de Python esté en tu PATH.

"Error: Docker is not available"

El escaneo de imágenes Docker requiere un daemon Docker en ejecución. Inicia Docker Desktop o el servicio Docker, luego reintenta. Si solo necesitas escanear código fuente, usa ggshield secret scan path o ggshield secret scan repo en su lugar.