Skill ggshield Scanner para OpenClaw

Visão Geral do Skill ggshield Scanner do OpenClaw

O skill ggshield Scanner traz o poderoso motor de detecção de segredos do GitGuardian para o seu workflow OpenClaw. Em vez de memorizar flags do CLI do ggshield e formatos de saída, você pode pedir ao OpenClaw para escanear seu código em busca de segredos vazados usando linguagem natural.

O ggshield detecta mais de 500 tipos de segredos hardcoded — chaves API, credenciais de banco de dados, tokens de nuvem, chaves privadas e mais. O skill OpenClaw ggshield scanner encapsula essas capacidades em uma interface conversacional, facilitando a execução de escaneamentos sob demanda, configuração de hooks pre-commit e interpretação de resultados sem sair do seu fluxo de desenvolvimento.

Workflow típico:

1. Peça ao OpenClaw para escanear seu projeto em busca de vazamentos de segredos.
2. O agente executa ggshield secret scan contra sua base de código ou arquivos específicos.
3. Os resultados são retornados em um resumo legível destacando segredos detectados, seus tipos e localizações — sem necessidade de analisar a saída bruta do CLI.

Seja auditando um repositório existente ou adicionando escaneamento de segredos ao seu processo de desenvolvimento, este skill cuida do trabalho pesado. Combine-o com o skill 1Password para um workflow completo de gerenciamento de segredos.

Pré-requisitos para o Skill ggshield Scanner

Antes de instalar o skill ggshield Scanner, certifique-se de ter:

• OpenClaw instalado e rodando (v1.0+)
• ggshield instalado — guia oficial de instalação
• Python 3.9+ (se instalar via pip/pipx) ou usar pacotes standalone
• Git instalado para escaneamento de repositórios
• clawhub CLI instalado para gerenciamento de skills — guia de instalação

Instale o ggshield usando seu método preferido:

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

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

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

Verifique sua configuração:

ggshield --version

Como Instalar o Skill ggshield Scanner

Instale o skill ggshield Scanner com um único comando:

npx clawhub@latest install ggshield-scanner

Para verificar a instalação:

clawhub list

Você deve ver ggshield-scanner na sua lista de skills instalados. O skill requer que o ggshield esteja disponível no seu PATH.

Configuração do Skill ggshield Scanner

Autenticação GitGuardian

O skill ggshield Scanner requer uma chave API do GitGuardian para detecção de segredos. Você pode se autenticar de duas formas:

Login interativo (recomendado para desenvolvimento local):

ggshield auth login

Isso abre seu navegador e gera automaticamente um token de acesso pessoal (PAT).

Variável de ambiente (recomendado para CI/CD):

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

Configuração de Variáveis de Ambiente

| Variável | Obrigatória | Descrição | |----------|------------|-----------| | GITGUARDIAN_API_KEY | Sim | Token de acesso pessoal do GitGuardian | | GITGUARDIAN_INSTANCE | Não | URL da instância GitGuardian on-premise |

Importante: Nunca faça hardcode da sua chave API em arquivos de configuração. Use variáveis de ambiente ou um gerenciador de segredos como 1Password ou Bitwarden.

Configuração de Hook Pre-commit

Para interceptar segredos antes de serem commitados:

# Instalar hook para o repositório atual
ggshield install --mode local

# Instalar hook globalmente para todos os repositórios
ggshield install --mode global

Exemplos de Uso do Skill ggshield Scanner

1. Escanear um Diretório de Projeto

Você: "Escaneie meu diretório do projeto em busca de segredos hardcoded"

O agente executa ggshield secret scan path -r . contra seu diretório de trabalho e retorna um resumo dos segredos detectados, incluindo caminho do arquivo, número da linha e tipo de segredo. Se nenhum segredo for encontrado, você recebe um relatório limpo confirmando que seu código está seguro.

2. Auditar o Histórico do Repositório Git

Você: "Verifique todo meu histórico git em busca de segredos vazados"

O agente executa ggshield secret scan repo . para escanear todos os commits no seu repositório. Isso é útil para auditar bases de código legadas ou garantir que segredos previamente commitados foram devidamente rotacionados e removidos.

3. Escanear uma Imagem Docker Antes do Deploy

Você: "Escaneie a imagem Docker nginx:latest em busca de segredos"

O agente executa ggshield secret scan docker nginx:latest para inspecionar todas as camadas da imagem Docker. Isso captura segredos que podem ter sido incorporados em imagens de contêiner durante o processo de build — uma fonte comum de vazamentos de credenciais em produção.

4. Configurar Proteção Pre-commit

Você: "Instale um hook pre-commit para bloquear segredos de serem commitados"

O agente executa ggshield install --mode local para adicionar um hook git pre-commit ao seu repositório. Cada commit futuro será automaticamente escaneado, e commits contendo segredos detectados serão bloqueados antes de chegarem ao seu repositório.

Segurança e Boas Práticas

Siga estas diretrizes ao usar o skill ggshield Scanner:

• Use escaneamentos somente leitura por padrão. O skill deve apenas escanear e reportar — evite auto-remediação sem revisar cuidadosamente cada descoberta.
• Revise antes de confirmar. Quando o agente sugerir remover ou rotacionar um segredo detectado, verifique se a descoberta é um verdadeiro positivo antes de agir.
• Rotacione segredos expostos imediatamente. Se o ggshield detectar um segredo real no histórico do seu repositório, rotacione a credencial imediatamente — remover o commit não é suficiente.
• Habilite hooks pre-commit. Prevenção é melhor que detecção. Configure hooks com ggshield install para capturar segredos antes que entrem no controle de versão.
• Mantenha o ggshield atualizado. Novos padrões de segredos são adicionados regularmente. Execute pipx upgrade ggshield ou brew upgrade ggshield para se manter atualizado.

Solução de Erros Comuns

"Error: Invalid API key"

Sua chave API do GitGuardian está faltando ou expirou. Reautentique com ggshield auth login ou verifique se sua variável de ambiente GITGUARDIAN_API_KEY está configurada corretamente. Verifique no painel do GitGuardian se o token não foi revogado.

"Error: ggshield command not found"

O ggshield não está instalado ou não está no seu PATH. Instale com pipx install ggshield ou brew install gitguardian/tap/ggshield. Se instalado via pip, certifique-se de que o diretório de scripts Python está no seu PATH.

"Error: Docker is not available"

O escaneamento de imagens Docker requer um daemon Docker em execução. Inicie o Docker Desktop ou o serviço Docker, então tente novamente. Se você só precisa escanear código fonte, use ggshield secret scan path ou ggshield secret scan repo em vez disso.