Utilizzare l'estensione di sicurezza Gemini CLI per le revisioni delle richieste di pull di GitHub

1. Introduzione

L'estensione di sicurezza Gemini CLI è un'estensione open source di Gemini CLI creata da Google che analizza il codice alla ricerca di rischi e vulnerabilità per la sicurezza. Puoi utilizzare l'estensione Security con Gemini CLI per identificare i problemi di sicurezza a livello locale, proprio come faresti con qualsiasi altra estensione Gemini CLI. Puoi anche richiamarlo per esaminare le richieste di pull su GitHub. In questo codelab, esamineremo come utilizzare l'estensione Security nel tuo repository GitHub.

Attività previste

• Configura l'autenticazione sicura da GitHub a Google Cloud
• Crea un flusso di lavoro GitHub Actions che chiama l'estensione di sicurezza Gemini CLI
• Eseguire una revisione della sicurezza su una richiesta di pull nuova o esistente utilizzando GitHub Actions

Cosa imparerai a fare

• Come utilizzare la federazione delle identità per i workload per l'autenticazione sicura da GitHub Actions a Google Cloud
• Scopri i vantaggi dell'utilizzo di un pool di identità del workload e di un provider di identità del workload rispetto a una chiave API Gemini per l'autenticazione
• Come eseguire una revisione della sicurezza con le PR
• Come interpretare le revisioni della sicurezza restituite dall'estensione Security

Che cosa ti serve

• Un browser web
• Un account e un repository GitHub
• Un progetto Google Cloud

Questo codelab è pensato per gli sviluppatori che conoscono il workflow CI/CD su GitHub. Non è necessario avere familiarità con Gemini CLI o le estensioni Gemini CLI. Se vuoi scoprire come funzionano le estensioni, consulta il codelab Introduzione alle estensioni Gemini CLI.

In questo codelab imparerai a configurare l'estensione di sicurezza della Gemini CLI nel tuo repository GitHub. Non suggeriremo codice per aprire una richiesta di pull nel tuo repository per attivare il rilevamento di una vulnerabilità di sicurezza.

2. Prima di iniziare

Per i crediti Google Cloud:per iniziare, riscatta i tuoi crediti Google Cloud senza costi. Segui le istruzioni per attivare il credito e creare un nuovo progetto.

Crea o seleziona un progetto

1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare la fatturazione.
3. Apri Cloud Shell, un ambiente a riga di comando in esecuzione in Google Cloud. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.

4. Una volta eseguita la connessione a Cloud Shell, verifica di essere autenticato e che il progetto sia impostato sul tuo ID progetto utilizzando il seguente comando:

gcloud auth list

5. Esegui questo comando per verificare che il comando gcloud sia configurato per utilizzare il tuo progetto.

gcloud config list project

6. Se il progetto non è impostato, utilizza il seguente comando per impostarlo:

gcloud config set project ${GOOGLE_CLOUD_PROJECT}

3. Configurare l'autenticazione da GitHub a Google Cloud

Come funziona

La federazione delle identità per i workload è il modo consigliato per eseguire l'autenticazione da GitHub Actions a Google Cloud.

1. Per ogni workflow esecuzione job di GitHub Actions, GitHub come provider di identità esterno emette un JWT (JSON Web Token) firmato. Questo token contiene "rivendicazioni" come repository, workflow e job_workflow_ref, che fungono da carta d'identità digitale per quel runner specifico. In questo lab creerai un flusso di lavoro GitHub Actions con un job che utilizza l'azione google-github-actions/run-gemini-cli, che richiederà un JWT da GitHub e invierà questo token al Security Token Service (STS) in Google Cloud.
2. Configurerai un pool di identità del workload e un provider in Google Cloud impostando l'URL dell'emittente sull'URL ufficiale del servizio di token GitHub https://token.actions.githubusercontent.com e definendo i mapping degli attributi, che in genere includono i nomi del repository e del ramo. Google Cloud STS convalida il JWT in base alle regole del pool di identità del workload. Se tutto, inclusi i mapping degli attributi, viene verificato, il servizio STS scambia il token GitHub con un token di accesso federato Google Cloud di breve durata.
3. Ora l'azione google-github-actions/run-gemini-cli nel flusso di lavoro GitHub Actions può utilizzare il token di accesso federato Google Cloud di breve durata per "simulare l'identità" di un service account connesso al pool di identità del workload. Il service account collegato deve disporre dei ruoli e delle autorizzazioni IAM necessari per accedere a qualsiasi risorsa e servizio Google Cloud.

   GitHub utilizza la federazione delle identità diretta senza la simulazione dell'identità del service account. Tuttavia, Gemini CLI richiede la creazione di un token del service account, che è supportata solo tramite la simulazione dell'identità del service account.

Vantaggi dell'utilizzo della federazione delle identità per i workload rispetto alla chiave API Gemini

È possibile autenticare le chiamate Gemini CLI originate da GitHub Actions utilizzando una chiave API Gemini, il che comporta la creazione di un nuovo secret di GitHub Actions denominato GEMINI_API_KEY con il valore della chiave appropriato. Tuttavia, questa soluzione è sconsigliata per i seguenti motivi di sicurezza:

• Le chiavi API Gemini possono disporre di autorizzazioni generali dai rispettivi binding dei ruoli IAM. Se compromesse, aprono l'accesso a una vasta gamma di risorse e servizi Google Cloud. La federazione delle identità per i workload utilizza service account e token di accesso di breve durata, il che rafforza notevolmente l'autenticazione.
• Anche le chiavi API Gemini sono difficili da gestire su larga scala. L'identificazione dei workflow che utilizzano una chiave esposta richiede tempo. Anche la rotazione manuale delle chiavi richiede tempo. D'altra parte, puoi cercare, modificare ed eliminare facilmente i pool e i fornitori di identità del workload associati al tuo repository dalla console Cloud.
• Con le chiavi API Gemini, devi sempre verificare di non esporle accidentalmente in log di accesso o di debug. Con la federazione delle identità per i workload, non memorizzi segreti dei flussi di lavoro GitHub Actions, ma variabili, che sono intrinsecamente meno sensibili.

Configura GitHub Actions e Google Cloud

1. In Cloud Shell, accedi al tuo account GitHub.

gh auth login

2. Crea un nuovo file setup_workload_identity.sh e copia e incolla lo script di configurazione dal repository google-github-actions/run-gemini-cli.
3. Trasforma lo script in un eseguibile.

chmod +x setup_workload_identity.sh

4. Esegui lo script.

./setup_workload_identity.sh --repo {OWNER/REPO} --project {GOOGLE_CLOUD_PROJECT}

4. Crea un flusso di lavoro GitHub Actions

1. Controlla un repository GitHub di tua proprietà.

git clone {YOUR_REPO}
cd {YOUR REPO}

2. Crea un flusso di lavoro GitHub Actions che richiama il comando slash /security:analyze-github-pr copiando uno script di flusso di lavoro di esempio yml dal repository /gemini-cli-extensions/security.

git checkout -b workflow
mkdir .github/ && cd .github/
mkdir workflows/ && cd workflows/
curl -L https://raw.githubusercontent.com/gemini-cli-extensions/security/refs/heads/main/.github/workflows/gemini-review.yml -o gemini-review.yml

3. Esegui il push del flusso di lavoro GitHub Actions nell'origine remota su GitHub.

git add .github/workflows/gemini-review.yml
git commit -m "add new gha workflow"
git push --set-upstream origin workflow

5. Esegui il flusso di lavoro di analisi della sicurezza su PR nuove ed esistenti

Avvia una nuova richiesta pull nel tuo repository GitHub o pubblica un nuovo commento "@gemini-cli /review" come proprietario o collaboratore del repository. Verrà avviata una revisione della sicurezza della richiesta pull. L'estensione di sicurezza Gemini CLI del flusso di lavoro GitHub Actions di cui hai eseguito il commit nel tuo repository taggherà eventuali risultati di sicurezza rilevati in base alle categorie di gravità da "Critica", "Alta", "Media" a "Bassa".

Ecco un esempio di revisione della sicurezza su una nuova richiesta pull e un esempio di revisione della sicurezza su una richiesta pull esistente.

6. Ulteriori esplorazioni

Ti invitiamo a esplorare un elenco crescente di comandi personalizzati con nuove funzionalità di sicurezza nell'estensione di sicurezza della Gemini CLI e a iniziare a utilizzarla nei tuoi workflow. Ad esempio:

• /security:scan-deps esegue un controllo incrociato delle dipendenze del progetto con OSV.dev.

Consulta le note di rilascio per conoscere le ultime funzionalità e correzioni di bug.

7. Complimenti

Congratulazioni, hai configurato correttamente il tuo repository GitHub per utilizzare l'estensione di sicurezza della Gemini CLI per analizzare le richieste di pull per rischi e vulnerabilità di sicurezza.