ggshield: proteggi il tuo codice con GitGuardian

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 tramite py-gitguardian per scansionare e rilevare potenziali vulnerabilità in file e altri contenuti testuali.

Solo metadati come tempo di chiamata, dimensione della richiesta e modalità di scansione vengono memorizzati dalle scansioni che utilizzano ggshield, quindi i segreti non verranno visualizzati nella tua dashboard e i tuoi file e segreti non verranno memorizzati.

Indice

• Installazione
  • Script di installazione (consigliato)
  • macOS
    • Homebrew
    • Pacchetto .pkg standalone
  • Linux
    • Pacchetti Deb e RPM
  • Windows
    • Chocolatey
    • Installazione MSI
    • Archivio .zip standalone
  • Tutti i sistemi operativi
    • Usando pipx
    • Usando pip
• Configurazione iniziale
  • Usando ggshield auth login
  • Configurazione manuale
• Per iniziare
  • Segreti
  • Migrazione di un file di configurazione legacy
• Integrazioni
  • Assistenti di codifica AI
• Ulteriori informazioni
• Output
• Progetti open source correlati
• Licenza

Installazione

Script di installazione (consigliato)

Il modo più rapido per installare 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

Oppure, se preferisci curl (incluso con Windows 10+):

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 lo spazio di lavoro EU o un'istanza self-hosted, imposta la variabile d'ambiente GITGUARDIAN_INSTANCE (o passa --instance <URL>) prima di eseguirlo.

Vedi scripts/install/README.md per l'elenco completo delle opzioni, gli altri metodi di installazione e come disinstallare.

I metodi seguenti installano invece manualmente la CLI.

macOS

Homebrew

Puoi installare ggshield usando Homebrew:

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.

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.

Istruzioni per l'installazione:

• Pacchetti Deb
• Pacchetti RPM

L'aggiornamento è gestito dal gestore di pacchetti.

Windows

Chocolatey

ggshield è disponibile tramite Chocolatey package manager:

choco install ggshield

Installazione MSI

Scarica l'installazione MSI dalla pagina delle release di ggshield e installala:

msiexec /i ggshield-VERSION-x86_64-pc-windows-msvc.msi

Archivio .zip standalone

Forniamo un archivio .zip standalone sulla pagina delle release di ggshield.

Decomprimi l'archivio sul disco, quindi aggiungi la directory contenente il file ggshield.exe a %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.

Richiede una versione supportata di Python (non EOL) (eccetto per i pacchetti standalone) e git.

Se non utilizzi le nostre versioni impacchettate di ggshield, tieni presente che seguiamo il ciclo di rilascio di Python e non supportiamo versioni che hanno raggiunto EOL.

Usando pipx

Il modo consigliato per installare ggshield da PyPI è usare pipx, che lo installerà in un ambiente isolato:

pipx install ggshield

Per aggiornare la tua installazione, esegui:

pipx upgrade ggshield

Usando pip

Puoi anche installare ggshield da PyPI usando pip, ma non è consigliato perché l'installazione non è isolata, quindi altre applicazioni o pacchetti installati in questo modo potrebbero influenzare la tua installazione di ggshield. Questo metodo inoltre non funzionerà se la tua installazione Python è dichiarata come gestita esternamente (ad esempio quando si utilizza Python di sistema su sistemi operativi come Debian 12):

pip install --user ggshield

Per aggiornare la tua installazione, esegui:

pip install --user --upgrade ggshield

Configurazione iniziale

Usando ggshield auth login

Per utilizzare ggshield devi autenticarti sui server GitGuardian. Per farlo, usa il comando ggshield auth login. Questo comando automatizza la creazione di un token di accesso personale e la sua configurazione sulla workstation locale.

Puoi saperne di più dalla documentazione di ggshield auth login.

Configurazione manuale

Puoi anche creare il tuo token di accesso personale manualmente 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 molto altro, 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:

ggshield config migrate

Per impostazione predefinita, cerca il file di configurazione nella directory corrente, quindi eseguilo dalla directory che contiene il file. Per eseguirlo da qualsiasi punto, indirizza ggshield esplicitamente al file:

ggshield --config-path path/to/.gitguardian.yaml config migrate

La versione precedente del file viene mantenuta come backup .old accanto ad esso.

Integrazioni

Puoi integrare ggshield nel tuo flusso di lavoro CI/CD.

Per intercettare gli errori prima, utilizza ggshield come hook Git pre-commit, pre-push o pre-receive.

Assistenti di codifica AI

ggshield può scansionare le interazioni 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 e Codex.

Ulteriori informazioni

Per maggiori informazioni, dai un'occhiata alla documentazione

Output

Se non sono stati trovati segreti, il codice di uscita sarà 0:

ggshield secret scan pre-commit

Se un segreto viene trovato nel tuo codice staged o nel tuo CI, riceverai un avviso che indica il nome del file in cui è stato trovato il segreto e una patch che indica la posizione del segreto nel file:

ggshield secret scan pre-commit

2 incidenti sono stati trovati nel 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 alla dimensione del terminale, a meno che non si utilizzi la modalità verbose (-v o --verbose).

Progetti open source correlati

• truffleHog
• gitleaks
• gitrob
• git-hound
• AWS git-secrets
• detect-secrets

Licenza

ggshield è concesso in licenza MIT.