GitGuardian check-hmsl: consulte exposição de segredos sem entregá-los ao agente

ANÁLISE EDITORIAL

Uma credencial encontrada em um inventário antigo pode continuar funcionando, mas isso não diz se já apareceu em uma fonte pública. A Skill check-hmsl, mantida pela GitGuardian, organiza uma consulta ao serviço HasMySecretLeaked (HMSL) sem entregar a senha ao agente de IA. O agente prepara o procedimento; a pessoa responsável roda o ggshield no próprio terminal e decide o que compartilhar do resultado. É um controle útil de exposição conhecida, não um atestado de que a credencial está segura.

O que a Skill faz

O SKILL.md auditado explica a diferença entre procurar segredos desconhecidos em código e consultar um segredo conhecido. Neste segundo caso, o ggshield hmsl calcula o hash localmente e envia prefixos para pesquisa no corpus público indexado pelo HMSL. A comparação do hash completo ocorre no computador da pessoa. O protocolo reduz a exposição do valor em claro na consulta, mas não protege uma credencial que alguém já colou no chat, em um log ou em uma captura. Por isso a Skill proíbe o agente de abrir arquivos de credenciais e de executar os comandos HMSL.

O serviço pode informar que uma credencial corresponde a material conhecido na base consultada. Um resultado sem correspondência só significa que ela não foi encontrada nesse corpus no momento da consulta. Não prova ausência de vazamento em outras fontes, nem substitui rotação, revogação, análise de uso indevido ou resposta a incidente. A visão geral oficial descreve o alcance e o funcionamento do HMSL.

Para quem serve e quando não usar

É apropriada para uma equipe de segurança que precisa verificar um token herdado, uma lista sob sua custódia ou uma suspeita de exposição antes de decidir a remediação. Também oferece um roteiro para inventários controlados em gerenciadores de segredos compatíveis, mas essa modalidade exige aprovação e entendimento do escopo. Se o objetivo é descobrir valores desconhecidos em um repositório, esta não é a ferramenta indicada; use uma varredura própria para código. Se a credencial não pertence à sua organização ou não há autorização para examiná-la, não faça a consulta.

Compatibilidade e pré-requisitos

O arquivo segue o formato Agent Skills e declara necessidade de ggshield 1.49.0 ou posterior. A execução HMSL é sempre feita pela pessoa no terminal local, não pelo agente. O acesso pode ser anônimo para uma verificação pequena, sujeito a quota menor, ou autenticado com conta GitGuardian. Instale o CLI separadamente pela documentação oficial de início; o ZIP desta página não contém programa, instalador nem token. Confira a versão instalada com ggshield --version e a conectividade com ggshield hmsl api-status, sem anexar arquivos de segredo à conversa.

Para execução em massa, consulte antes ggshield hmsl quota. A referência de quota é a fonte para os limites vigentes; não fixamos números porque eles podem mudar conforme autenticação e serviço. A pasta com credenciais deve ser controlada pela equipe, com permissões locais adequadas e política de descarte.

Instalação e configuração

Baixe o pacote documental local e confira o SHA-256 informado adiante. Extraia em uma pasta check-hmsl do diretório de Skills aceito pelo agente. Preserve a subpasta references: o SKILL.md aponta para ggshield-cli-setup.md e gitguardian-platform.md por caminhos relativos. Leia ORIGEM.md e LICENSE. Se o agente só carrega Skills no começo da sessão, inicie uma nova sessão para que ele a detecte. O repositório oficial pode trazer atualizações posteriores, que exigem nova revisão.

Não configure o agente para ler a pasta dos segredos, mesmo para “validar” formato ou contar linhas. A Skill funciona como transferência de comandos. Quem executa escolhe o arquivo e conhece seu conteúdo; o agente não precisa saber o nome real, o valor ou o caminho completo. Se for necessária autenticação, a pessoa segue ggshield auth login no seu próprio terminal, ou usa o procedimento oficial adequado ao ambiente. Não envie token de API ao chat.

Primeiro uso e resultado esperado

Peça ao agente: “Prepare um procedimento de HMSL para uma credencial da minha organização. Não leia nem execute nada contra o arquivo; explique como revisar uma saída sem nomes e sem valores”. Para um arquivo de texto sob controle da pessoa, o comando que a Skill exemplifica é ggshield hmsl check /caminho/para/segredos.txt --json -n none. O caminho é substituído localmente pela própria pessoa; não cole o segredo na linha de comando nem na conversa. Para um arquivo em formato .env, a Skill mostra a opção -t env. Antes de vários itens, a pessoa confere a quota.

A opção -n none evita que nomes ou valores sejam mostrados na saída compartilhável; --json facilita uma leitura estruturada. Ainda assim, revise o JSON localmente antes de enviar qualquer trecho ao agente. Nunca use --naming-strategy cleartext em material que possa chegar a uma conversa ou log. O resultado esperado é uma indicação de correspondência ou ausência de correspondência para os itens examinados, mais a informação necessária para abrir um processo interno de resposta. Não publique essa saída.

Permissões, privacidade e riscos

O usuário precisa de autorização para consultar as credenciais e de acesso de leitura local ao arquivo. O agente não precisa dessas permissões. A documentação descreve uma consulta por prefixos de hash; isso não torna inofensiva a leitura do arquivo por outras ferramentas nem garante anonimato absoluto em qualquer contexto. A Skill também veda --full-hashes por mudar a postura de privacidade. Para um resultado positivo, trate a credencial como exposta: acione o responsável, planeje revogação ou rotação, investigue uso e dependências, e documente o incidente conforme a política da organização. Para resultado negativo, mantenha os controles habituais e não conclua “sem risco”.

Erros comuns e limites

Se ggshield não for reconhecido, instale o CLI pela fonte oficial e confirme ggshield --version. Se api-status mostrar falha de autenticação, confirme o modo de uso e faça login local quando necessário. Se a quota acabar ou houver HTTP 429, veja ggshield hmsl quota e aguarde ou use uma conta autorizada com quota adequada; não altere para hashes completos apenas para contornar o limite. Se houver erro de arquivo ou formato, a pessoa revisa localmente caminho, codificação e tipo, sem pedir ao agente que abra a credencial. A documentação HMSL deve prevalecer sobre instruções desatualizadas do pacote.

Versão, licença e download local

Esta curadoria fixou o commit 425e5ac0a1f4f7b05e1e2d6b899a37007064cc3a, com versão declarada 0.6.2 no SKILL.md e release v0.6.2. O repositório tem licença MIT, que permite redistribuir esses arquivos com o aviso de licença. O pacote inclui somente SKILL.md, LICENSE, ORIGEM.md e dois documentos de referência em Markdown. Não inclui executáveis, dependências, credenciais ou arquivos de usuários.

Na consulta à API do GitHub em 15 de outubro de 2026, o repositório registrava 10 estrelas. Esta é uma exceção ao critério usual de 1.000 estrelas porque a Skill é mantida oficialmente pela GitGuardian e tem documentação, release e licença verificáveis. Dez estrelas não demonstram adoção ampla nem segurança operacional. SHA-256 do ZIP: 3f5a4a2f845c753bc6ad5bbb1f4b6807b840c424983cb361aa01894f681d7df4. Compare o hash do arquivo baixado antes de instalar.

Fontes primárias

Consulte o arquivo original da Skill, a visão geral do HMSL, as instruções do ggshield e a release do mantenedor. O ZIP próprio e o botão para o repositório oficial são destinos distintos: um reproduz a cópia auditada, o outro permite acompanhar a fonte.