Permessi minimi per il workflow e per ogni job

GITHUB_TOKEN consente a GitHub Actions di autenticarsi per eseguire operazioni in un repository. La chiave permissions ne configura i diritti per l’intero workflow o per singoli job, così ogni attività riceve solo le capacità di cui ha bisogno.

Come punto di partenza, GitHub consiglia di impostare il permesso predefinito di GITHUB_TOKEN sulla lettura dei contenuti del repository e di ampliarlo quando un job specifico lo richiede. Se un workflow si limita a consultare file, non ha bisogno di permessi di scrittura per comodità.

I permessi devono corrispondere all’operazione: per creare una issue serve issues: write; altre attività possono richiedere permessi diversi. Puoi impostare una base a livello di workflow e modificare i permessi del job che esegue l’operazione. Non ampliare i permessi di tutti i job per risolvere un’esigenza circoscritta.

Anche le action possono accedere al token tramite il contesto github.token, pur senza riceverlo come input. Limita quindi i permessi e controlla quali action vengono eseguite in ciascun job. Non passare esplicitamente secrets.GITHUB_TOKEN non dimostra che un’action non possa accedere al token.

Esempio di workflow in sola lettura

Il modello seguente si attiva quando vengono inviati cambiamenti a main e concede l’accesso in lettura ai contenuti del repository. Prima di usarlo, sostituisci actions/checkout@<SHA_COMPLETO_VERIFICATO> con uno SHA completo reale e verificato; il segnaposto non è un riferimento eseguibile.

Modello adattabile: sostituisci il segnaposto con uno SHA completo verificato prima di salvare ed eseguire il workflow.

name: Verifica modifiche

on:
  push:
    branches: [main]

permissions:
  contents: read

jobs:
  verifica:
    runs-on: ubuntu-latest
    steps:
      - name: Recupera il codice
        uses: actions/checkout@<SHA_COMPLETO_VERIFICATO>

      - name: Esegui i controlli
        run: ./scripts/check.sh

Bloccare un’action su uno SHA completo riduce il rischio che un tag cambi destinazione, ma non dimostra che il codice sia sicuro. Verifica che lo SHA appartenga al repository previsto e controlla il codice delle action utilizzate. GitHub presenta i file di lock delle dipendenze come una protezione più solida rispetto al solo blocco degli SHA.

Adatta i permessi al lavoro effettivo. Se non devi consultare il repository, valuta se contents: read sia necessario. Se aggiungi un’operazione di scrittura, individua il permesso richiesto e concedilo al job interessato, invece di ampliare l’accesso dell’intero workflow.

Concedere la scrittura solo al job che ne ha bisogno

Per creare una issue con GitHub CLI, un job richiede il permesso issues: write. Nell’esempio documentato da GitHub, il permesso viene configurato per il job e il token viene fornito allo strumento tramite la variabile d’ambiente GH_TOKEN.

name: Crea issue

on:
  workflow_dispatch:

jobs:
  crea-issue:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - name: Crea issue con GitHub CLI
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: gh issue create --title "Attività automatizzata" --body "Esamina il risultato del workflow."

Non inserire i segreti direttamente nei file del workflow e non stamparli nei log. GitHub avverte che il mascheramento automatico non è garantito per i valori trasformati. Se una credenziale compare senza protezione in un log, elimina il log interessato e ruota la credenziale.

Se GITHUB_TOKEN non offre i permessi necessari, GitHub documenta alcune alternative: un token di installazione di una GitHub App oppure un token di accesso personale salvato come segreto. Applica il principio del privilegio minimo e limita chi può accedere a tali credenziali.

Pull request esterne e attività privilegiate

Il contenuto di una pull request esterna va trattato come input non attendibile: chi la invia può controllare il codice, gli script e le dipendenze eseguiti durante i test. GitHub Security Lab indica che, per le richieste provenienti da fork, l’evento pull_request blocca per impostazione predefinita i permessi di scrittura e l’accesso ai segreti del repository di destinazione.

pull_request_target viene eseguito nel contesto del repository di destinazione e può avere permessi di scrittura e accesso ai segreti. Il rischio nasce quando questo contesto privilegiato viene combinato con il recupero e l’esecuzione di codice esterno: script, test e installazioni di pacchetti controllati da chi invia la PR possono eseguire codice nell’ambiente del workflow.

Non eseguire codice non attendibile in un job privilegiato. pull_request_target può essere adatto ad attività limitate, come aggiungere etichette o commenti, se il workflow non esegue codice controllato dalla pull request. Un checkout esplicito, da solo, non prova che si sia verificato uno sfruttamento: il contenuto può anche essere trattato come dato passivo, ma non deve controllare i processi di compilazione, test o installazione.

Per testare codice esterno, usa un workflow non privilegiato con pull_request. Se in seguito devi pubblicare un risultato con permessi di scrittura, puoi separare i test da questa attività usando workflow_run. Gli artefatti prodotti dalla pull request restano dati non attendibili: il workflow privilegiato può leggere le informazioni necessarie, ma non deve eseguire binari o script provenienti da tali artefatti.

Controlla anche le pull request già aperte quando hai modificato un workflow vulnerabile. GitHub Security Lab avverte che una richiesta in sospeso può continuare a usare la versione del workflow esistente al momento dell’apertura; potrebbe essere necessario chiuderla o aggiornarla in modo controllato.

Pull requests externos y tareas privilegiadas El contenido de un pull request externo debe tratarse como entrada no confiable: quien lo presenta puede controlar código, scripts y d...
Illustrazione editoriale di BytePreview

Input, action e segreti

I dati di una pull request possono raggiungere la shell attraverso le espressioni del workflow. Per ridurre il rischio di injection, GitHub consiglia di assegnare il valore esterno a una variabile d’ambiente intermedia e usare tale variabile nello script, invece di interpolare direttamente il dato nel comando.

Anche le action di terze parti richiedono una verifica. I job possono condividere informazioni o risorse e un’action compromessa può influire sul token e sui segreti a sua disposizione. Esamina il codice di ogni action e controlla che non invii segreti a destinazioni inattese né li scriva nei log.

Per i workflow che accedono a servizi cloud compatibili, GitHub consiglia di valutare l’autenticazione OIDC invece di conservare come segreti credenziali di lunga durata. Se un job richiede segreti di un ambiente, puoi configurare revisori obbligatori affinché l’accesso dipenda da un’approvazione.

Riduci i segreti disponibili a quelli indispensabili e verifica come vengono usati. Il mascheramento dei log è utile, ma non sostituisce la separazione tra codice attendibile e non attendibile; ruota le credenziali se vengono esposte.

Checklist per un workflow esistente

Inizia identificando l’evento che attiva ciascun job, quindi segui il percorso attraverso permessi, action, segreti e dati di input. Non cercare soltanto secrets.GITHUB_TOKEN: un’action può accedere al token tramite github.token.

  • Il job può funzionare con permessi di lettura anziché di scrittura?
  • Il permesso di scrittura è limitato al job che esegue l’operazione?
  • Un workflow privilegiato elabora codice o artefatti provenienti da una pull request esterna?
  • Le action sono bloccate su SHA completi verificati e il loro codice viene controllato?
  • I valori esterni arrivano alla shell tramite variabili d’ambiente intermedie?
  • I segreti sono indispensabili e si evita che compaiano nei log?

Nei repository pubblici, presta particolare attenzione ai runner self-hosted. GitHub avverte che codice non attendibile può comprometterli in modo persistente. Descrive invece i propri runner hosted come macchine virtuali effimere e pulite; questa descrizione non è una garanzia per i runner self-hosted e non elimina la necessità di limitare permessi e segreti.

Come regola operativa, combina lettura predefinita, scrittura quando serve e isolamento del codice esterno. Dopo aver testato un workflow, controlla i log per verificare che le informazioni sensibili non siano state esposte e ruota ogni credenziale compromessa.