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](https://github.com/GitGuardian/ggshield): proteja seu código com o 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: a atualização para a versão 1.54.0 aciona um prompt do Keychain para `ggshield-py`**, um segundo binário que agora lê seu token salvo como parte das nossas melhorias de desempenho. Clique em **Always Allow** (Sempre Permitir); ele não perguntará novamente.
`ggshield` é uma aplicação CLI que é executada no 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](https://api.gitguardian.com/docs) através do [py-gitguardian](https://github.com/GitGuardian/py-gitguardian) para escanear e detectar possíveis vulnerabilidades em arquivos e outros conteúdos de texto.
Apenas metadados como horário da chamada, tamanho da requisição e modo de escaneamento são armazenados dos escaneamentos usando `ggshield`, portanto os segredos não serão exibidos no seu dashboard e **seus arquivos e segredos não serão armazenados**.
# Índice
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
- [Instalação](#installation)
- [Script de instalação (Recomendado)](#install-script-recommended)
- [macOS](#macos)
- [Homebrew](#homebrew)
- [Pacote .pkg autônomo](#standalone-pkg-package)
- [Linux](#linux)
- [Pacotes Deb e RPM](#deb-and-rpm-packages)
- [Windows](#windows)
- [Chocolatey](#chocolatey)
- [Instalador MSI](#msi-installer)
- [Arquivo .zip autônomo](#standalone-zip-archive)
- [Todos os sistemas operacionais](#all-operating-systems)
- [Usando pipx](#using-pipx)
- [Usando pip](#using-pip)
- [Configuração inicial](#initial-setup)
- [Usando `ggshield auth login`](#using-ggshield-auth-login)
- [Configuração manual](#manual-setup)
- [Primeiros passos](#getting-started)
- [Segredos](#secrets)
- [Migrando um arquivo de configuração legado](#migrating-a-legacy-configuration-file)
- [Integrações](#integrations)
- [Assistentes de codificação com IA](#ai-coding-assistants)
- [Saiba mais](#learn-more)
- [Saída](#output)
- [Projetos de código aberto relacionados](#related-open-source-projects)
- [Licença](#license)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
# Instalação
<!--
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 instalação (Recomendado)
A maneira mais rápida de instalar o `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
```
Ou, se você preferir `curl` (incluído no Windows 10+):
```powershell
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.
Consulte [`scripts/install/README.md`](https://github.com/gitguardian/ggshield/blob/main/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.
## macOS
### Homebrew
Você pode instalar o `ggshield` usando o Homebrew:
```shell
brew install ggshield
```
A atualização é gerenciada pelo Homebrew.
### Pacote .pkg autônomo
Alternativamente, você pode baixar e instalar um pacote .pkg autônomo da [página de releases do `ggshield`](https://github.com/GitGuardian/ggshield/releases).
Este pacote _não_ requer a instalação do Python, mas você precisa baixar manualmente as novas versões.
## Linux
### Pacotes Deb e RPM
Pacotes Deb e RPM estão disponíveis no [Cloudsmith](https://cloudsmith.io/~gitguardian/repos/ggshield/packages/).
Instruções de configuração:
- [Pacotes Deb](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-deb)
- [Pacotes RPM](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-rpm)
A atualização é gerenciada pelo gerenciador de pacotes.
## Windows
### Chocolatey
`ggshield` está disponível através do [gerenciador de pacotes Chocolatey](https://chocolatey.org/packages/ggshield):
```shell
choco install ggshield
```
### Instalador MSI
Baixe o instalador MSI da [página de releases do `ggshield`](https://github.com/GitGuardian/ggshield/releases) e instale-o:
```powershell
msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi
```
### Arquivo .zip autônomo
Fornecemos um arquivo .zip autônomo na [página de releases do `ggshield`](https://github.com/GitGuardian/ggshield/releases).
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 a instalação do Python, mas você precisa baixar manualmente as novas versões.
## Todos os sistemas operacionais
`ggshield` pode ser instalado em todos os sistemas operacionais suportados através do seu [pacote PyPI](https://pypi.org/project/ggshield).
Ele requer **uma versão suportada do Python (não EOL)** (exceto para pacotes autônomos) e git.
Se você não usa nossas versões empacotadas do `ggshield`, esteja ciente de que seguimos o [ciclo de lançamento do Python](https://devguide.python.org/versions/) e não oferecemos suporte a versões que atingiram o EOL.
### Usando pipx
A maneira recomendada de instalar o `ggshield` a partir do PyPI é usar o [pipx](https://pypa.github.io/pipx/), que o instalará em um ambiente isolado:
```shell
pipx install ggshield
```
Para atualizar sua instalação, execute:
```shell
pipx upgrade ggshield
```
### Usando pip
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 estiver declarada como gerenciada externamente (por exemplo, ao usar o Python do sistema em sistemas operacionais como Debian 12):
```shell
pip install --user ggshield
```
Para atualizar sua instalação, execute:
```shell
pip install --user --upgrade ggshield
```
# Configuração inicial
## Usando `ggshield auth login`
Para usar o `ggshield` você precisa se autenticar nos servidores do GitGuardian. Para 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 saber mais sobre isso na [documentação do `ggshield auth login`](https://docs.gitguardian.com/internal-repositories-monitoring/ggshield/reference/auth/login).
Após autenticar, execute `ggshield machine setup` para configurar hooks de IA e git,
plantar honeytokens e registrar a máquina na página Endpoints antes do seu primeiro
escaneamento. O registro inclui o usuário atual, ou todos os usuários alvo de honeytoken quando
executado como root. É feito em melhor esforço, leva no máximo cinco segundos e não afeta
o código de saída do comando.
Os escaneamentos de `ggshield secret scan pre-commit`, `pre-push` e `ai-hook` também enviam
o hostname da máquina, a partir do qual o GitGuardian registra os usuários desses hooks.
Outros comandos de escaneamento não o enviam, nem o hook de IA nativo que as instalações
autônomas e específicas de plataforma via `pip` executam.
Em CI, o ggshield não registra a máquina nem envia o hostname. Para desativar ambos
em outros lugares, defina `endpoint_registration: false` em `.gitguardian.yaml`, ou defina
`GGSHIELD_NO_ENDPOINT_REGISTRATION` com um valor não vazio.
## Configuração manual
Você também pode criar seu token de acesso pessoal manualmente e armazená-lo na variável de ambiente `GITGUARDIAN_API_KEY` para completar a configuração.
# Primeiros passos
## Segredos
Agora você pode usar o `ggshield` para procurar segredos:
- em arquivos: `ggshield secret scan path -r .`
- em repositórios: `ggshield secret scan repo .`
- em imagens Docker (o comando `docker` deve estar disponível): `ggshield secret scan docker ubuntu:22.04`
- em pacotes Pypi (o comando `pip` deve estar disponível): `ggshield secret scan pypi flask`
- e mais, dê uma olhada na saída de `ggshield secret scan --help` para detalhes.
## Migrando um arquivo de configuração legado
Se o `ggshield` informar que seu arquivo de configuração `.gitguardian.yaml` (ou `.gitguardian.yml`) usa um formato obsoleto, migre-o para a versão mais recente com:
```shell
ggshield config migrate
```
Por padrão, isso 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` explicitamente para o arquivo:
```shell
ggshield --config-path path/to/.gitguardian.yaml config migrate
```
A versão anterior do arquivo é mantida como um backup `.old` ao lado dele.
# Integrações
Você pode integrar o `ggshield` no seu [fluxo de trabalho de CI/CD](https://docs.gitguardian.com/ggshield-docs/integrations/overview#cicd-integrations-secrets-detection-in-your-cicd-workflow).
Para detectar erros mais cedo, use o `ggshield` como um [hook Git de pre-commit, pre-push ou pre-receive](https://docs.gitguardian.com/ggshield-docs/integrations/overview#git-hooks-prevent-secrets-from-reaching-your-vcs).
## Assistentes de codificação com IA
`ggshield` pode [escanear interações](https://docs.gitguardian.com/ggshield-docs/integrations/ai-coding-tools/secret-scanning-for-ai-coding-tools) entre você e seu assistente de codificação com 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**, **Codex** e
**Mistral Vibe 2.21+**.
# Saiba mais
Para mais informações, consulte [a documentação](https://docs.gitguardian.com/ggshield-docs/getting-started)
# Saída
Se nenhum segredo for encontrado, o código de saída será 0:
```bash
ggshield secret scan pre-commit
```
Se um segredo for encontrado no seu código em stage ou na sua CI, você receberá um alerta informando o nome do arquivo onde o segredo foi encontrado e um patch mostrando a posição do segredo no arquivo:
```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 | }
```
Linhas muito longas são truncadas para corresponder ao tamanho do terminal, a menos que o modo verboso seja usado (`-v` ou `--verbose`).
# Projetos de código aberto 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)
# Licença
`ggshield` é licenciado sob MIT.