gitguardian/ggshieldRileva e convalida oltre 500 tipi di segreti hardcoded con controlli avanzati. Usalo come pre-commit hook, GitHub Action o CLI per la rilevazione proattiva di segreti e la sicurezza.
# [ggshield](https://github.com/GitGuardian/ggshield): proteggi il tuo codice con 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: l'aggiornamento alla versione 1.54.0 attiva una richiesta del Portachiavi per `ggshield-py`**, un secondo binario che ora legge il token salvato come parte dei nostri miglioramenti delle prestazioni. Fai clic su **Consenti sempre**; non lo chiederà più.
`ggshield` è un'applicazione CLI che viene eseguita nel tuo ambiente locale o in un ambiente CI per aiutarti a rilevare più di 500 tipi di segreti.
`ggshield` utilizza la nostra [API pubblica](https://api.gitguardian.com/docs) tramite [py-gitguardian](https://github.com/GitGuardian/py-gitguardian) per scansionare e rilevare potenziali vulnerabilità nei file e in altri contenuti testuali.
Dalle scansioni effettuate con `ggshield` vengono memorizzati solo metadati come l'ora della chiamata, la dimensione della richiesta e la modalità di scansione, pertanto i segreti non verranno visualizzati nella tua dashboard e **i tuoi file e segreti non verranno memorizzati**.
# Indice
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
- [Installazione](#installazione)
- [Script di installazione (consigliato)](#script-di-installazione-consigliato)
- [macOS](#macos)
- [Homebrew](#homebrew)
- [Pacchetto .pkg standalone](#pacchetto-pkg-standalone)
- [Linux](#linux)
- [Pacchetti Deb e RPM](#pacchetti-deb-e-rpm)
- [Windows](#windows)
- [Chocolatey](#chocolatey)
- [Programma di installazione MSI](#programma-di-installazione-msi)
- [Archivio .zip standalone](#archivio-zip-standalone)
- [Tutti i sistemi operativi](#tutti-i-sistemi-operativi)
- [Utilizzo di pipx](#utilizzo-di-pipx)
- [Utilizzo di pip](#utilizzo-di-pip)
- [Configurazione iniziale](#configurazione-iniziale)
- [Utilizzo di `ggshield auth login`](#utilizzo-di-ggshield-auth-login)
- [Configurazione manuale](#configurazione-manuale)
- [Per iniziare](#per-iniziare)
- [Segreti](#segreti)
- [Migrazione di un file di configurazione legacy](#migrazione-di-un-file-di-configurazione-legacy)
- [Integrazioni](#integrazioni)
- [Assistenti di codifica AI](#assistenti-di-codifica-ai)
- [Ulteriori informazioni](#ulteriori-informazioni)
- [Output](#output)
- [Progetti open source correlati](#progetti-open-source-correlati)
- [Licenza](#licenza)
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
# Installazione
<!--
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 di installazione (consigliato)
Il modo più rapido per installare `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
```
Oppure, se preferisci `curl` (incluso in Windows 10+):
```powershell
curl.exe -sSL https://raw.githubusercontent.com/GitGuardian/ggshield/main/scripts/install/install.ps1 | powershell -NoProfile -ExecutionPolicy Bypass -Command -
```
Lo script accetta opzioni come `--instance` e `--plugin` (installa un
plugin). Per il workspace UE o un'istanza self-hosted, imposta la
variabile d'ambiente `GITGUARDIAN_INSTANCE` (o passa `--instance <URL>`)
prima dell'esecuzione.
Consulta [`scripts/install/README.md`](https://github.com/gitguardian/ggshield/blob/main/scripts/install/README.md) per l'elenco completo
delle opzioni, gli altri metodi di installazione e come disinstallare.
I metodi seguenti installano la CLI manualmente.
## macOS
### Homebrew
Puoi installare `ggshield` usando Homebrew:
```shell
brew install ggshield
```
L'aggiornamento è gestito da Homebrew.
### Pacchetto .pkg standalone
In alternativa, puoi scaricare e installare un pacchetto .pkg standalone dalla [pagina delle release di `ggshield`](https://github.com/GitGuardian/ggshield/releases).
Questo pacchetto _non_ richiede l'installazione di Python, ma devi scaricare manualmente le nuove versioni.
## Linux
### Pacchetti Deb e RPM
I pacchetti Deb e RPM sono disponibili su [Cloudsmith](https://cloudsmith.io/~gitguardian/repos/ggshield/packages/).
Istruzioni di configurazione:
- [Pacchetti Deb](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-deb)
- [Pacchetti RPM](https://cloudsmith.io/~gitguardian/repos/ggshield/setup/#formats-rpm)
L'aggiornamento è gestito dal gestore di pacchetti.
## Windows
### Chocolatey
`ggshield` è disponibile tramite il [gestore di pacchetti Chocolatey](https://chocolatey.org/packages/ggshield):
```shell
choco install ggshield
```
### Programma di installazione MSI
Scarica il programma di installazione MSI dalla [pagina delle release di `ggshield`](https://github.com/GitGuardian/ggshield/releases) e installalo:
```powershell
msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi
```
### Archivio .zip standalone
Forniamo un archivio .zip standalone sulla [pagina delle release di `ggshield`](https://github.com/GitGuardian/ggshield/releases).
Estrai l'archivio sul tuo disco, quindi aggiungi la directory contenente il file `ggshield.exe` al `%PATH%`.
Questo archivio _non_ richiede l'installazione di Python, ma devi scaricare manualmente le nuove versioni.
## Tutti i sistemi operativi
`ggshield` può essere installato su tutti i sistemi operativi supportati tramite il suo [pacchetto PyPI](https://pypi.org/project/ggshield).
Richiede **una versione supportata di Python (non EOL)** (tranne che per i pacchetti standalone) e git.
Se non utilizzi le nostre versioni pacchettizzate di `ggshield`, tieni presente che seguiamo il [ciclo di rilascio di Python](https://devguide.python.org/versions/) e non supportiamo le versioni che hanno raggiunto l'EOL.
### Utilizzo di pipx
Il modo consigliato per installare `ggshield` da PyPI è usare [pipx](https://pypa.github.io/pipx/), che lo installerà in un ambiente isolato:
```shell
pipx install ggshield
```
Per aggiornare la tua installazione, esegui:
```shell
pipx upgrade ggshield
```
### Utilizzo di pip
Puoi anche installare `ggshield` da PyPI usando pip, ma questo non è consigliato perché l'installazione non è isolata, quindi altre applicazioni o pacchetti installati in questo modo potrebbero influire sulla tua installazione di `ggshield`. Questo metodo inoltre non funzionerà se la tua installazione di Python è dichiarata come gestita esternamente (ad esempio quando si utilizza il Python di sistema su sistemi operativi come Debian 12):
```shell
pip install --user ggshield
```
Per aggiornare la tua installazione, esegui:
```shell
pip install --user --upgrade ggshield
```
# Configurazione iniziale
## Utilizzo di `ggshield auth login`
Per usare `ggshield` devi autenticarti sui server GitGuardian. Per farlo, usa il comando `ggshield auth login`. Questo comando automatizza il provisioning di un token di accesso personale e la sua configurazione sulla workstation locale.
Puoi saperne di più dalla [documentazione di `ggshield auth login`](https://docs.gitguardian.com/internal-repositories-monitoring/ggshield/reference/auth/login).
Dopo l'autenticazione, esegui `ggshield machine setup` per configurare gli hook AI e git,
piantare honeytoken e registrare la macchina nella pagina Endpoints prima della sua prima
scansione. La registrazione include l'utente corrente, o tutti gli utenti target degli honeytoken quando
eseguita come root. È best effort, richiede al massimo cinque secondi e non influisce
sul codice di uscita del comando.
Le scansioni di `ggshield secret scan pre-commit`, `pre-push` e `ai-hook` inviano anche
il nome host della macchina, dal quale GitGuardian registra gli utenti di questi hook.
Gli altri comandi di scansione non lo inviano, né lo fa l'hook AI nativo eseguito dalle installazioni
standalone e specifiche della piattaforma tramite `pip`.
In CI, ggshield non registra la macchina né invia il nome host. Per disattivare entrambi
altrove, imposta `endpoint_registration: false` in `.gitguardian.yaml`, oppure imposta
`GGSHIELD_NO_ENDPOINT_REGISTRATION` su un valore non vuoto.
## Configurazione manuale
Puoi anche creare manualmente il tuo token di accesso personale e memorizzarlo nella variabile d'ambiente `GITGUARDIAN_API_KEY` per completare la configurazione.
# Per iniziare
## Segreti
Ora puoi usare `ggshield` per cercare segreti:
- nei file: `ggshield secret scan path -r .`
- nei repository: `ggshield secret scan repo .`
- nelle immagini Docker (il comando `docker` deve essere disponibile): `ggshield secret scan docker ubuntu:22.04`
- nei pacchetti Pypi (il comando `pip` deve essere disponibile): `ggshield secret scan pypi flask`
- e altro ancora, dai un'occhiata all'output di `ggshield secret scan --help` per i dettagli.
## Migrazione di un file di configurazione legacy
Se `ggshield` segnala che il tuo file di configurazione `.gitguardian.yaml` (o `.gitguardian.yml`) utilizza un formato deprecato, migralo all'ultima versione con:
```shell
ggshield config migrate
```
Per impostazione predefinita, questo cerca il file di configurazione nella directory corrente, quindi eseguilo dalla directory che contiene il file. Per eseguirlo da qualsiasi posizione, indica esplicitamente il file a `ggshield`:
```shell
ggshield --config-path path/to/.gitguardian.yaml config migrate
```
La versione precedente del file viene conservata come backup `.old` accanto ad esso.
# Integrazioni
Puoi integrare `ggshield` nel tuo [flusso di lavoro CI/CD](https://docs.gitguardian.com/ggshield-docs/integrations/overview#cicd-integrations-secrets-detection-in-your-cicd-workflow).
Per individuare gli errori in anticipo, usa `ggshield` come [hook Git pre-commit, pre-push o pre-receive](https://docs.gitguardian.com/ggshield-docs/integrations/overview#git-hooks-prevent-secrets-from-reaching-your-vcs).
## Assistenti di codifica AI
`ggshield` può [scansionare le interazioni](https://docs.gitguardian.com/ggshield-docs/integrations/ai-coding-tools/secret-scanning-for-ai-coding-tools) tra te e il tuo assistente di codifica AI in tempo reale, bloccando le azioni che contengono segreti prima che vengano eseguite.
Puoi installare gli hook con il comando `ggshield install`.
Strumenti supportati: **Cursor**, **Claude Code**, **Copilot Chat**, **Codex** e
**Mistral Vibe 2.21+**.
# Ulteriori informazioni
Per maggiori informazioni, dai un'occhiata alla [documentazione](https://docs.gitguardian.com/ggshield-docs/getting-started)
# Output
Se non è stato trovato alcun segreto, il codice di uscita sarà 0:
```bash
ggshield secret scan pre-commit
```
Se viene trovato un segreto nel tuo codice in stage o nella tua CI, riceverai un avviso che ti fornisce il nome del file in cui è stato trovato il segreto e una patch che ti indica la posizione del segreto nel file:
```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 | }
```
Le righe troppo lunghe vengono troncate per adattarsi alle dimensioni del terminale, a meno che non venga utilizzata la modalità dettagliata (`-v` o `--verbose`).
# Progetti open source correlati
- [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)
# Licenza
`ggshield` è distribuito con licenza MIT.