Pinning e sicurezza delle GitHub Actions

Come contromisura agli attacchi supply chain sui pacchetti, come pinnare le dipendenze GitHub Actions da versione a hash SHA, inclusa la strategia di aggiornamento automatico via Dependabot.

Per contrastare i rischi di attacchi o manomissioni alle action di GitHub, il progetto ufficiale Laravel adotta il pinning delle GitHub Actions. Questa pagina illustra in modo pratico le contromisure di sicurezza che dovresti implementare come sviluppatore di pacchetti.

Questa pagina è la sorella di Sviluppo di pacchetti Laravel. Si presume una conoscenza di base di GitHub Actions.

​

Rischi di sicurezza delle GitHub Actions

​

La pericolosità dei riferimenti basati su tag

Normalmente le GitHub Actions si referenziano tramite tag:

- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2

Problemi di questo approccio:

• I tag sono mobili — un tag può essere cancellato e ricreato mantenendo lo stesso nome
• Rischio di manomissione — se l’account del proprietario del repository viene compromesso, si può iniettare codice malevolo
• Attacco supply chain — un attacco a un’action da cui dipendi compromette il tuo workflow

​

Come lo affrontano i progetti ufficiali Laravel

In laravel/laravel e laravel/framework tutte le action sono pinnate a un commit hash (SHA).

# riferimento sicuro
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4

​

Strategia di implementazione del pinning

​

Passo 1: creare il file di configurazione Dependabot

Nel repository del pacchetto crea .github/dependabot.yml. Puoi copiare quello di Laravel così com’è.

version: 2
updates:
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    cooldown:
      default-days: 5
    groups:
      github-actions:
        patterns:
          - "*"

Il file svolge questi ruoli:

• Scansione automatica — cerca nuove versioni delle GitHub Actions
• Creazione automatica di PR — apre PR di aggiornamento quando c’è una novità
• Controllo del metodo di aggiornamento — aggiorna per versione le action non pinnate, per SHA quelle pinnate

​

Passo 2: pinnare le action esistenti a SHA

Cambia tutti i riferimenti delle action nei workflow esistenti in hash SHA. Puoi automatizzarlo con strumenti come pinact.

​

Automazione con pinact

# pinna a SHA le action nei workflow
pinact run

​

Modifiche manuali

Se non puoi usare pinact, consulta la pagina Lookup latest version di GitHub per trovare gli SHA di ogni action e sostituiscili a mano.

# prima
- uses: actions/checkout@v4
- uses: shivammathur/setup-php@v2
  with:
    php-version: ${{ matrix.php }}

# dopo
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4
- uses: shivammathur/setup-php@0a92e4568cab5c87b7175192630661408458a086  # v2
  with:
    php-version: ${{ matrix.php }}

​

Passo 3: abilitare la configurazione Dependabot

Committa e pusha .github/dependabot.yml: Dependabot avvierà la scansione automaticamente.

​

Meccanismo di aggiornamento automatico via Dependabot

Dependabot applica strategie diverse in base alle impostazioni di dependabot.yml.

​

Action non pinnata

# prima del pinning
- uses: actions/checkout@v4

Aggiornamento Dependabot: aggiorna il range di versione a quello nuovo

# PR creata da Dependabot
- uses: actions/checkout@v5

Comoda ma con rischi di sicurezza residui: risponde al movimento del tag ma non protegge dalla manomissione.

​

Action pinnata

# dopo il pinning
- uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4

Aggiornamento Dependabot: aggiorna al commit hash della nuova versione

# PR creata da Dependabot
- uses: actions/checkout@f1d3225b54b677ba3e72df8c464cb6cf6dc1aebf  # v4

L’approccio più sicuro. Anche con una nuova versione, il riferimento è comunque un commit hash: molto più resistente alle manomissioni.

​

Esempio completo di workflow

Esempio completo quando usi action in più workflow.

name: Tests

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    
    strategy:
      fail-fast: false
      matrix:
        php: [8.2, 8.3, 8.4]
        laravel: ["^12.0", "^13.0"]

    steps:
      - uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4
        with:
          fetch-depth: 0

      - name: Setup PHP
        uses: shivammathur/setup-php@0a92e4568cab5c87b7175192630661408458a086  # v2
        with:
          php-version: ${{ matrix.php }}
          extensions: dom, curl, libxml, mbstring, zip, intl, sqlite3
          coverage: none

      - name: Install dependencies
        run: |
          composer require "laravel/framework:${{ matrix.laravel }}" \
                           --no-interaction --no-update
          composer update --prefer-dist --no-interaction

      - name: Run tests
        run: vendor/bin/pest

  lint:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@a5ac7e51b41094c7fcab2042361574b0021804ab  # v4

      - name: Setup PHP
        uses: shivammathur/setup-php@0a92e4568cab5c87b7175192630661408458a086  # v2
        with:
          php-version: "8.4"
          extensions: dom, curl, libxml, mbstring, zip
          coverage: none

      - name: Install dependencies
        run: composer install --prefer-dist --no-interaction

      - name: Run static analysis
        run: vendor/bin/phpstan

​

Gestire le PR di aggiornamento Dependabot

Le PR di aggiornamento create da Dependabot si gestiscono così.

​

PR di aggiornamento di una singola action

Bump shivammathur/setup-php from v1 to v2

Aggiornamento semplice, procedi così:

1. Controlla il risultato dell’esecuzione del workflow
2. Verifica che non ci siano breaking change
3. Merge e chiudi

​

PR di aggiornamento di sicurezza

[SECURITY] Bump actions/checkout to a5ac7e51b41094c7fcab2042361574b0021804ab

Priorità massima per i fix di sicurezza: mergea per prima.

​

Aggiornamenti raggruppati

Se in dependabot.yml hai impostato groups, più action vengono aggiornate in un’unica PR.

groups:
  github-actions:
    patterns:
      - "*"

Raggruppare tutti gli aggiornamenti in una sola PR riduce il numero di merge.

​

Vantaggi e svantaggi del pinning

​

Vantaggi

Vantaggio	Descrizione
Contromisura supply chain	Referenziando uno specifico commit hash, contrasti la manomissione delle action
Auditabilità	Puoi tracciare quando ogni action è stata aggiornata e da quale versione
Aggiornamenti espliciti	Dependabot propone gli aggiornamenti in PR, quindi passano sempre da una review umana
Riproducibilità	Con lo stesso commit hash riottieni esattamente lo stesso ambiente

​

Svantaggi

Svantaggio	Come gestirlo
Setup iniziale manuale	Automatizza con lo strumento pinact
Maggior carico di gestione degli aggiornamenti	Dependabot crea PR automaticamente, minimizzando il costo di implementazione
Meno leggibilità	Aggiungi commenti con la versione per la leggibilità

​

Checklist di audit di sicurezza

Checklist per l’avvio di un nuovo progetto pacchetto.

Setup iniziale

• Creare .github/dependabot.yml
• Pinnare tutte le action esistenti a SHA
• Aver completato la verifica con pinact o a mano
• Verificare che i workflow si eseguano correttamente

Manutenzione periodica

• Rivedere le PR di aggiornamento Dependabot almeno una volta a settimana
• Merge prioritari degli aggiornamenti di sicurezza
• Referenziare sempre a SHA le action nuove
• Una volta al mese verificare lo stato di tutti i workflow

Audit

• Verifica che tutti i riferimenti alle action siano su SHA
• Verifica che Dependabot sia abilitato
• Verifica che tutte le PR di Dependabot degli ultimi 6 mesi siano state mergeate

​

Pagine correlate

Nozioni di sviluppo dei pacchetti

Come sviluppare pacchetti Laravel imperniati sui service provider.

Gestire la compatibilità tra versioni dei pacchetti

Strategie di adattamento dei pacchetti agli upgrade major di Laravel.