Una chiave API finisce nel repository: prevenzione e verifica del percorso di revoca

Parliamo del tuo progetto →

Quando una chiave API entra in un repository, il problema non si risolve cancellando una riga. Serve un flusso completo: prevenzione prima del push, gestione dell’eventuale blocco, revoca presso il provider, sostituzione nei servizi che dipendono dalla credenziale e verifica finale.

GitHub descrive la push protection come un controllo che può intercettare segreti hardcoded prima che arrivino nel repository; disponibilità e copertura dipendono dalla configurazione. La documentazione segnala anche che, in alcuni casi, un utente autorizzato può superare il blocco con un bypass tracciato. GitHub Docs — Push protection

Perché il punto non è solo “bloccare il commit”

Per chi sviluppa, la domanda pratica è: cosa succede quando la protezione si attiva? Per chi guida IT o sicurezza, il tema è definire un percorso ripetibile: chi riceve l’avviso, chi decide la revoca, chi aggiorna i servizi dipendenti e chi chiude l’incidente.

La distinzione da tenere sempre ferma è questa:

rilevazione: il sistema intercetta un segreto potenziale;
risposta: si decide come procedere;
revoca e rotazione: la credenziale viene invalidata e sostituita;
verifica: si controlla che nessun servizio stia ancora usando il segreto esposto.

GitHub raccomanda di trattare un segreto esposto come compromesso: rimuovere il file o riscrivere la history non basta se la credenziale è già stata copiata. GitHub Docs — Remediating a leaked secret in your repository, GitHub Docs — Secret scanning

Preparare una simulazione senza credenziali reali

Questo è un esempio didattico simulato. Non usare mai una chiave vera per “testare” lo scanner.

Obiettivo della simulazione

L’obiettivo non è dimostrare che un sistema riconosca qualsiasi testo, ma verificare il processo:

segnalazione del segreto;
decisione sul bypass o sul blocco;
revoca presso il provider;
distribuzione della sostituzione;
controllo finale sui servizi collegati.

Prerequisiti

un repository di test separato da produzione;
un segnaposto fittizio e chiaramente non valido;
un referente per sicurezza o operations che conosca il provider della credenziale;
un canale per registrare allerta, bypass e passaggi di revoca.

Input simulato

Inserisci nel repository un valore chiaramente fittizio, per esempio:

API_KEY_TEST=non_usare_questa_chiave

L’obiettivo non è vedere se lo scanner “indovina” un segreto qualsiasi, ma esercitare il flusso di risposta.

Come impostare il laboratorio

1) Verificare la prevenzione prima del push

Abilita la protezione sul repository o sull’organizzazione, se la policy del progetto lo prevede. La documentazione GitHub indica che la push protection può essere configurata a più livelli e non è necessariamente attiva in ogni contesto. GitHub Docs — Push protection

Controlla anche:

quali tipi di segreti vengono intercettati;
chi può autorizzare un eventuale bypass;
come viene registrata l’eccezione;
quali notifiche partono verso i ruoli responsabili.

2) Registrare il messaggio di blocco o la notifica

Se il controllo si attiva, annota solo il riferimento tecnico necessario: mai il valore completo del segreto.

La scheda dell’incidente dovrebbe contenere almeno:

tipo di credenziale;
repository o servizio coinvolto;
owner della credenziale;
ruolo che ha visto l’allerta;
decisione presa.

3) Identificare il proprietario della credenziale

Prima della revoca bisogna capire chi può intervenire davvero. Il punto non è “chi ha visto il problema”, ma:

quale servizio usa la chiave;
quale fornitore la governa;
chi può revocarla;
dove va distribuita la sostituzione.

Se nessuno conosce queste dipendenze, la lacuna è già un risultato utile dell’esercizio.

4) Revocare presso il provider

La revoca dipende dal tipo di credenziale e dal servizio che la emette. GitHub documenta un flusso generale di revoca e, per alcune credenziali GitHub, anche un’API dedicata; il dettaglio operativo cambia in base al provider e al token coinvolto. GitHub Docs — Revocation

In pratica, il laboratorio deve chiarire:

se la credenziale appartiene a GitHub oppure a un servizio esterno;
se esiste una procedura automatizzabile;
se la revoca richiede un’azione manuale nel pannello del provider;
chi conferma l’avvenuta revoca.

5) Sostituire il segreto nei sistemi dipendenti

Una chiave revocata deve essere rimpiazzata nei punti in cui era usata:

applicazione;
pipeline;
job schedulati;
integrazioni esterne;
eventuali ambienti di test o staging.

La sostituzione va distribuita con il meccanismo previsto dall’organizzazione, non a mano e in modo improvvisato.

6) Controllare log e accessi anomali

Dopo la revoca, verifica il periodo compreso tra esposizione e contenimento. Cerca accessi anomali, errori di autenticazione, richieste sospette o uso del segreto su sistemi che non dovrebbero più averlo.

Output atteso della simulazione

Il risultato non è “il segreto è stato cancellato”, ma una scheda chiusa con questi elementi:

credenziale identificata;
owner nominato;
provider individuato;
revoca eseguita;
sostituzione distribuita;
verifica conclusa sui servizi dipendenti.

Controlli di accettazione

La verifica va fatta da ruoli distinti, in momenti diversi:

Sviluppatore: conferma di aver rimosso il riferimento dal codice o dal file di configurazione.
Security manager: conferma che la revoca sia stata richiesta ed eseguita.
Operations: conferma che i servizi abbiano ricevuto il nuovo segreto e non usino più quello esposto.
Responsabile di rilascio: conferma che il bypass, se avvenuto, sia stato registrato e approvato secondo policy.

Limiti da dichiarare nel pezzo

La push protection non garantisce di intercettare ogni segreto. Il bypass, quando consentito, non è un fallimento del processo ma una deroga che deve lasciare traccia e richiedere revisione. Inoltre, revocare una credenziale non elimina da sola tutti i rischi se il segreto è già finito in log, fork, backup o copie locali.

Per questo il laboratorio va presentato come esercizio operativo, non come prova di copertura totale. La simulazione serve a misurare la qualità del flusso, non a dimostrare che qualsiasi stringa venga riconosciuta dallo scanner.

Perché questo flusso è utile alle PMI

Per una PMI il vantaggio non è solo tecnico. Un percorso chiaro riduce tempi morti, evita discussioni improvvisate tra sviluppo e sicurezza e aiuta a capire subito se un’incidenza resta un incidente minore o diventa un problema operativo più ampio.

In altre parole: meno incertezza sulla proprietà della chiave, meno ritardi sulla revoca, più rapidità nel ripristino.

Se il tuo team gestisce repository, API e integrazioni, il punto da mettere a fuoco non è soltanto se il repository blocca il segreto. È se l’organizzazione sa revocarlo, sostituirlo e verificare che i servizi dipendenti abbiano smesso di usarlo.