gitguardian/ggshieldDetecte e valide mais de 500 tipos de segredos codificados com verificações avançadas. Use-o como hook de pré-commit, GitHub Action ou CLI para detecção proativa de segredos e segurança.
ggshield é um aplicativo CLI que roda em seu ambiente local ou em um ambiente de CI para ajudá-lo a detectar mais de 500 tipos de segredos.
ggshield usa nossa API pública através do py-gitguardian para escanear e detectar potenciais vulnerabilidades em arquivos e outros conteúdos de texto.
Apenas metadados como tempo de chamada, tamanho da solicitação e modo de varredura são armazenados a partir de varreduras usando ggshield, portanto, os segredos não serão exibidos no seu painel e seus arquivos e segredos não serão armazenados.
A maneira mais rápida de instalar o 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
Ou, se você preferir curl (incluído no Windows 10+):
curl.exe -sSL https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | powershell -NoProfile -ExecutionPolicy Bypass -Command -
O script aceita opções como --instance e --plugin (instalar um plugin). Para o workspace da UE ou uma instância auto-hospedada, defina a variável de ambiente GITGUARDIAN_INSTANCE (ou passe --instance <URL>) antes de executar.
Veja scripts/install/README.md para a lista completa de opções, os outros métodos de instalação e como desinstalar.
Os métodos abaixo instalam a CLI manualmente.
Você pode instalar o ggshield usando Homebrew:
brew install ggshield
A atualização é gerenciada pelo Homebrew.
Alternativamente, você pode baixar e instalar um pacote .pkg independente da página de lançamentos do ggshield.
Este pacote não requer instalação do Python, mas você precisa baixar manualmente novas versões.
Pacotes Deb e RPM estão disponíveis no Cloudsmith.
Instruções de configuração:
A atualização é gerenciada pelo gerenciador de pacotes.
ggshield está disponível através do gerenciador de pacotes Chocolatey:
choco install ggshield
Baixe o instalador MSI da página de lançamentos do ggshield e instale-o:
msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi
Fornecemos um arquivo .zip independente na página de lançamentos do ggshield.
Descompacte o arquivo no seu disco e adicione o diretório que contém o arquivo ggshield.exe ao %PATH%.
Este arquivo não requer instalação do Python, mas você precisa baixar manualmente novas versões.
ggshield pode ser instalado em todos os sistemas operacionais suportados através do seu pacote PyPI.
Requer uma versão suportada do Python (não EOL) (exceto para pacotes independentes) e git.
Se você não usar nossas versões empacotadas do ggshield, esteja ciente de que seguimos o ciclo de lançamento do Python e não suportamos versões que atingiram o fim da vida (EOL).
A maneira recomendada de instalar o ggshield a partir do PyPI é usar o pipx, que o instalará em um ambiente isolado:
pipx install ggshield
Para atualizar sua instalação, execute:
pipx upgrade ggshield
Você também pode instalar o ggshield a partir do PyPI usando pip, mas isso não é recomendado porque a instalação não é isolada, então outros aplicativos ou pacotes instalados dessa forma podem afetar sua instalação do ggshield. Este método também não funcionará se sua instalação do Python for declarada como gerenciada externamente (por exemplo, ao usar o Python do sistema em sistemas operacionais como Debian 12):
pip install --user ggshield
Para atualizar sua instalação, execute:
pip install --user --upgrade ggshield
ggshield auth loginPara usar o ggshield, você precisa se autenticar nos servidores do GitGuardian. Para fazer isso, use o comando ggshield auth login. Este comando automatiza o provisionamento de um token de acesso pessoal e sua configuração na estação de trabalho local.
Você pode aprender mais sobre isso na documentação do ggshield auth login.
Você também pode criar seu token de acesso pessoal manualmente e armazená-lo na variável de ambiente GITGUARDIAN_API_KEY para concluir a configuração.
Agora você pode usar o ggshield para pesquisar segredos:
ggshield secret scan path -r .ggshield secret scan repo .docker deve estar disponível): ggshield secret scan docker ubuntu:22.04pip deve estar disponível): ggshield secret scan pypi flaskggshield secret scan --help para detalhes.Se o ggshield relatar que seu arquivo de configuração .gitguardian.yaml (ou .gitguardian.yml) usa um formato obsoleto, migre-o para a versão mais recente com:
ggshield config migrate
Por padrão, ele procura o arquivo de configuração no diretório atual, então execute-o a partir do diretório que contém o arquivo. Para executá-lo de qualquer lugar, aponte o ggshield para o arquivo explicitamente:
ggshield --config-path path/to/.gitguardian.yaml config migrate
A versão anterior do arquivo é mantida como um backup .old ao lado dele.
Você pode integrar o ggshield no seu fluxo de trabalho CI/CD.
Para detectar erros mais cedo, use ggshield como um hook Git pre-commit, pre-push ou pre-receive.
ggshield pode escanear interações entre você e seu assistente de codificação de IA em tempo real, bloqueando ações que contenham segredos antes que sejam executadas.
Você pode instalar os hooks com o comando ggshield install.
Ferramentas suportadas: Cursor, Claude Code, Copilot Chat e Codex.
Para mais informações, dê uma olhada na documentação
Se nenhum segredo for encontrado, o código de saída será 0:
ggshield secret scan pre-commit
Se um segredo for encontrado em seu código preparado ou em seu CI, você terá um alerta informando o nome do arquivo onde o segredo foi encontrado e um patch mostrando a posição do segredo no arquivo:
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 | }
Linhas muito longas são truncadas para corresponder ao tamanho do terminal, a menos que o modo verboso seja usado (-v ou --verbose).
ggshield é licenciado sob MIT.