GitHub: Scan Vulnerabilità Docker Trivy

Mirio · 12 Dicembre 2025, 2:44pm

La sicurezza delle immagini Docker è fondamentale in ogni ambiente di produzione. Se stai cercando come implementare la scansione automatica delle vulnerabilità nei tuoi container Docker, sei nel posto giusto.

In questa guida completa su Trivy Scanner e GitHub Actions imparerai a:

Automatizzare le scansioni di sicurezza con GitHub Actions
Visualizzare le vulnerabilità CVE nella Security tab di GitHub

Trivy è uno scanner di vulnerabilità open-source sviluppato da Aqua Security, semplice da usare e particolarmente efficace nell’identificare problemi di sicurezza in immagini Docker, filesystem, configuration files e dipendenze.

Requisiti per seguire questa guida

Repository GitHub con permessi elevati (almeno maintainer)
Un Dockerfile nel tuo progetto

Come Preparare il Repository GitHub per Trivy Scanner

Step 1: Configurare i Workflow Permissions su GitHub

Prima di implementare la scansione automatica con Trivy, dobbiamo abilitare i permessi necessari per permettere al workflow di pubblicare immagini Docker e caricare i risultati delle scansioni di sicurezza.

Come abilitare Read and Write permissions:

Apri il tuo repository su GitHub
Naviga in Settings → Actions → General
Scorri fino alla sezione Workflow permissions
Seleziona Read and write permissions
Clicca su Save per salvare le modifiche

Questa configurazione è essenziale per il GitHub Container Registry perché il workflow deve poter:

Pushare immagini Docker in Github Container Registry
Caricare report SARIF nella GitHub Security tab
Gestire i security events e vulnerability alerts

Step 2: Creare la Struttura per GitHub Actions Workflows

Per configurare GitHub Actions correttamente, devi creare la cartella standard .github/workflows dove GitHub cerca automaticamente i file di configurazione delle pipeline CI/CD.

Comando per creare la directory:

mkdir -p .github/workflows

Questa è la best practice per organizzare i workflow di GitHub Actions. Tutti i file YAML in questa directory verranno automaticamente riconosciuti come workflow eseguibili.

Creare il Workflow Trivy per GitHub Actions

Ora creeremo il file trivy.yaml all’interno della cartella appena creata che implementerà la pipeline di security scanning completa.

Il workflow si occuperà di:

Docker build dell’immagine container.
Push dell’immagine nel GitHub Container Registry.
Trivy vulnerability scan dell’immagine Docker.
Upload dei risultati CVE nella GitHub Security tab.

Configurazione Base del GitHub Actions Workflow

1. Nome e Variabili d’Ambiente per Docker Build

name: BuildAndScan

env:
  DOCKER_BUILDKIT: 1
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

Spiegazione delle variabili d’ambiente:

name: Nome identificativo del GitHub Actions workflow (visibile nella tab Actions)
DOCKER_BUILDKIT: 1: Abilita Docker BuildKit per build più veloci e cache avanzata
REGISTRY: ghcr.io: Indirizzo del GitHub Container Registry per pubblicare le immagini
IMAGE_NAME: Variabile dinamica che usa il formato username/repository automaticamente

2. Trigger Events: Quando Eseguire la Scansione Trivy

on:
  push:
    branches:
      - main
  pull_request:

Quando viene eseguito il vulnerability scanning:

Ad ogni git push sul branch main (o master)
Ad ogni apertura o aggiornamento di Pull Request
Puoi aggiungere altri branch per estendere la copertura security

Questa configurazione implementa il concetto di shift-left security, scansionando le vulnerabilità prima del merge in produzione.

GitHub Actions Job: Build e Push Docker Image

Il primo job del workflow implementa la Docker build e il push nel registry.

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      id-token: write
    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Setup Docker buildx
        uses: docker/setup-buildx-action@v3

      - name: Log into registry ${{ env.REGISTRY }}
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract Docker metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: ${{ github.sha }}

      - name: Build and push Docker image
        id: build-and-push
        uses: docker/build-push-action@v6
        with:
          context: .
          file: Dockerfile
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          provenance: false
          cache-from: type=gha
          cache-to: type=gha,mode=max

Analisi Dettagliata: Come Funziona il Docker Build su GitHub Actions

1. Git Checkout del Codice Sorgente

- name: Checkout code
  uses: actions/checkout@v6

Scarica il codice del repository nel GitHub Actions runner. Questo step è fondamentale per accedere al Dockerfile e ai file necessari per la build.

2. Configurazione Docker Buildx

- name: Setup Docker buildx
  uses: docker/setup-buildx-action@v3

Installa e configura Docker Buildx, necessario per:

Build multi-piattaforma (AMD64, ARM64)
Cache layer avanzata
Performance migliorate

3. Login Automatico a GitHub Container Registry

- name: Log into registry ${{ env.REGISTRY }}
  uses: docker/login-action@v3
  with:
    registry: ${{ env.REGISTRY }}
    username: ${{ github.actor }}
    password: ${{ secrets.GITHUB_TOKEN }}

Effettua l’autenticazione a GHCR (ghcr.io) usando:

GITHUB_TOKEN: Token automatico fornito da GitHub (no configurazione richiesta)
github.actor: Username dell’utente che ha triggerato il workflow

4. Estrazione Metadata Docker

- name: Extract Docker metadata
  id: meta
  uses: docker/metadata-action@v5
  with:
    images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
    tags: ${{ github.sha }}

Genera automaticamente Docker tags e labels basati su:

Commit SHA (identificativo univoco)
Branch name
Metadata del repository

5. Build e Push dell’Immagine Docker

- name: Build and push Docker image
  id: build-and-push
  uses: docker/build-push-action@v6
  with:
    context: .
    file: Dockerfile
    push: true
    tags: ${{ steps.meta.outputs.tags }}
    labels: ${{ steps.meta.outputs.labels }}
    provenance: false
    cache-from: type=gha
    cache-to: type=gha,mode=max

Effettua la build effettiva dell’immagine e procede all’upload.

Parametri chiave per ottimizzare la Docker build:

cache-from/cache-to: Usa la GitHub Actions cache per velocizzare build successive
provenance: false: Disabilita metadata SBOM (opzionale, riduce dimensione immagine)
push: true: Pubblica automaticamente nel registry

Risultato: L’immagine è ora disponibile su:

ghcr.io/<username>/<repository>:<commit-sha>

GitHub Actions Job: Trivy Vulnerability Scanner

Il secondo job implementa la scansione automatica delle vulnerabilità con Trivy Scanner.

  trivy_imagevuln:
    name: Trivy Scanner - Image
    runs-on: ubuntu-latest
    needs: build
    permissions:
      contents: read
      security-events: write
    steps:
    - name: Run Trivy vulnerability scanner
      uses: aquasecurity/[email protected]
      with:
        image-ref: '${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}'
        format: 'sarif'
        output: 'trivy-results.sarif'
        
    - name: Upload Trivy scan results to GitHub Security tab
      uses: github/codeql-action/upload-sarif@v4
      with:
        sarif_file: 'trivy-results.sarif'

Come Funziona la Scansione Trivy: Analisi Tecnica

Configurazione del Job di Security Scanning

needs: build: Dipendenza job precedente - Trivy scansiona solo dopo build completata
permissions:
- contents: read: Lettura codice repository
- security-events: write: Permesso essenziale per scrivere nella GitHub Security tab

Step 1: Esecuzione Trivy Vulnerability Scanner

- name: Run Trivy vulnerability scanner
  uses: aquasecurity/[email protected]
  with:
    image-ref: '${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}'
    format: 'sarif'
    output: 'trivy-results.sarif'

Parametri Trivy Scanner:

image-ref: URL completo dell’immagine Docker da scansionare
format: 'sarif': SARIF (Static Analysis Results Interchange Format) - formato standard per GitHub Security
output: File di output con tutte le CVE (Common Vulnerabilities and Exposures) trovate

Step 2: Upload Risultati nella GitHub Security Tab

- name: Upload Trivy scan results to GitHub Security tab
  uses: github/codeql-action/upload-sarif@v4
  with:
    sarif_file: 'trivy-results.sarif'

Carica il report SARIF nella Security tab.

Questo crea una vista unificata di tutte le vulnerabilità del progetto.

Codice Completo: GitHub Actions Workflow con Trivy Scanner

Ecco il codice completo del workflow da salvare in .github/workflows/trivy.yaml:

name: BuildAndScan

env:
  DOCKER_BUILDKIT: 1
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  build:
    name: Build
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
      id-token: write
    steps:
      - name: Checkout code
        uses: actions/checkout@v6

      - name: Setup Docker buildx
        uses: docker/setup-buildx-action@v3

      - name: Log into registry ${{ env.REGISTRY }}
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract Docker metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: ${{ github.sha }}

      - name: Build and push Docker image
        id: build-and-push
        uses: docker/build-push-action@v6
        with:
          context: .
          file: Dockerfile
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          provenance: false
          cache-from: type=gha
          cache-to: type=gha,mode=max

  trivy_imagevuln:
    name: Trivy Scanner - Image
    runs-on: ubuntu-latest
    needs: build
    permissions:
      contents: read
      security-events: write
    steps:
    - name: Run Trivy vulnerability scanner
      uses: aquasecurity/[email protected]
      with:
        image-ref: '${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}'
        format: 'sarif'
        output: 'trivy-results.sarif'
        
    - name: Upload Trivy scan results to GitHub Security tab
      uses: github/codeql-action/upload-sarif@v4
      with:
        sarif_file: 'trivy-results.sarif'

Se hai dubbi circa il codice o il risultato puoi controllare questo repository creato ad-hoc.

Come Testare ed Eseguire il Workflow Trivy

Attivazione Automatica del Vulnerability Scanning

Step per attivare la scansione Trivy:

Crea il file di configurazione:

# Crea il file workflow
touch .github/workflows/trivy.yaml

# Incolla il codice completo nel file

Commit e push su GitHub:

git add .github/workflows/trivy.yaml
git commit -m "feat: Add Trivy security scanning with GitHub Actions"
git push origin main

Il workflow si avvia automaticamente - nessuna configurazione aggiuntiva richiesta

Monitorare l’Esecuzione del Workflow su GitHub

Come verificare lo stato della pipeline:

Apri il repository su GitHub
Clicca sulla tab Actions (in alto)
Visualizzerai il workflow “BuildAndScan” in esecuzione
Clicca sul workflow per vedere:
- Build job progress
- Trivy scanning progress
- Log dettagliati di ogni step
Attendi il completamento

Come Visualizzare le Vulnerabilità Trovate da Trivy

Dopo il completamento del vulnerability scanning, accedi ai risultati così:

Navigazione nella GitHub Security Tab:

Vai nella tab Security del repository
Nel menu laterale, clicca su Vulnerability alerts
Seleziona Code scanning
Vedrai una lista organizzata delle vulnerabilità CVE trovate da Trivy

Ad esempio:

Formato dei Risultati della Scansione:

Le vulnerabilità CVE sono organizzate per severità:

Critical: Risolvi immediatamente
High: Alta priorità
Medium: Media priorità
Low: Bassa priorità

Informazioni disponibili per ogni vulnerabilità:

Nome CVE (es. CVE-2024-12345)
Severity score CVSS
Package affetto e versione vulnerabile
Versione corretta consigliata
Descrizione tecnica del problema
Link a database CVE esterni (NVD, MITRE)

Dettagli Approfonditi delle CVE:

Cliccando su una singola vulnerabilità, GitHub mostra:

Descrizione completa del security issue
Impatto potenziale sul sistema
Remediation steps e fix disponibili
Riferimenti esterni (CVE database, security advisories)
CVSS score breakdown

Ad esempio:

Best Practices: Container Security e DevSecOps

1. Come Gestire le Vulnerabilità Docker Trovate da Trivy

Tecniche di risoluzione comuni:

Aggiorna la versione del package vulnerabile
Usa immagini base Docker più recenti
Rimuovi packages non necessari dal container
Applica security patches del vendor

Valutazione del rischio reale: Non tutte le CVE sono sfruttabili nel tuo contesto.

Valuta:

Il package vulnerabile è effettivamente usato?
La vulnerabilità è raggiungibile dall’esterno?
Esistono mitigazioni alternative (network policies, WAF)?

2. Ottimizzazione del Workflow GitHub Actions con Trivy

Bloccare Merge su Vulnerabilità Critiche

Implementa policy-as-code per prevenire deploy non sicuri ad esempio:

- name: Run Trivy vulnerability scanner
  uses: aquasecurity/[email protected]
  with:
    image-ref: '${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}'
    format: 'sarif'
    output: 'trivy-results.sarif'
    severity: 'CRITICAL,HIGH'
    exit-code: '1'  # ❌ Workflow fallisce se trova vulnerabilità critiche

Combinalo con GitHub Branch Protection Rules per impedire merge:

Settings → Branches → Add rule
Abilita Require status checks to pass
Seleziona Trivy Scanner - Image

3. Continuous Monitoring: Scansioni Schedulate

Oltre alle scansioni on-push, implementa scheduled scanning per immagini già pubblicate:

on:
  schedule:
    - cron: '0 0 * * 0'  # Ogni domenica a mezzanotte
  push:
    branches:
      - main
  pull_request:

Perché? Nuove CVE vengono scoperte quotidianamente, anche immagini “vecchie” possono diventare vulnerabili.

Troubleshooting: Problemi Comuni con Trivy e GitHub Actions

Errore: Workflow Fails al Login del Registry

Sintomo:

Error: failed to login to registry ghcr.io

Causa: Permessi insufficienti per GitHub Actions

Soluzione passo-passo:

Vai in Settings → Actions → General
Sotto “Workflow permissions”, seleziona Read and write permissions
Salva e rilancia il workflow
Verifica che il job abbia packages: write nei permissions

Errore: Risultati Non Appaiono nella Security Tab

Sintomo: Workflow completato con successo ma nessuna vulnerabilità visibile in Security

Cause possibili:

1. Permessi mancanti:

permissions:
  security-events: write  #  Questo è ESSENZIALE
  contents: read

2. Security features non abilitate:

Vai in Settings → Code security and analysis
Abilita “Code scanning”

3. SARIF format non corretto: Verifica che il parametro sia:

format: 'sarif'  # Non 'json' o 'table'

Errore: Docker Build Molto Lenta

Problema: Build impiega 10+ minuti

Ottimizzazioni consigliate:

Verifica utilizzo cache:

cache-from: type=gha
cache-to: type=gha,mode=max

Conclusioni: DevSecOps con Trivy e GitHub Actions

Congratulazioni! Hai configurato con successo un sistema che implementa:

Build automation di Docker images con GitHub Actions
Vulnerability scanning automatico con Trivy Scanner
CVE tracking integrato nella GitHub Security tab
DevSecOps best practices per container security

Vantaggi Ottenuti

1. Security Automation

Zero configurazione manuale dopo setup iniziale
Scansioni automatiche ad ogni push/PR
Nessun costo aggiuntivo (GitHub Actions free tier: 2000 min/mese)

2. Visibilità Centralizzata

Tutte le vulnerabilità CVE in un’unica dashboard
Tracking storico delle vulnerability

3. Prevenzione Proattiva

Identificazione vulnerabilità PRIMA del deploy
Blocco automatico su vulnerabilità critiche
Compliance semplificata per audit security

Risorse Avanzate per Approfondire

** Documentazione Ufficiale:**

Trivy Official Docs - Documentazione completa scanner
GitHub Actions Security Hardening - Best practices security
Container Security Best Practices - OWASP guidelines

Tools Complementari:

Grype - Alternative vulnerability scanner by Anchore
Snyk - Commercial scanner con free tier
Clair - Open-source scanner by CoreOS/RedHat

FAQ: Domande Frequenti su Trivy e GitHub Actions

Q: Trivy è gratuito anche per uso commerciale?
Sì, Trivy è completamente open-source (Apache 2.0 license) e gratuito anche per progetti enterprise.

Q: Quante scansioni posso fare al mese gratuitamente?
GitHub Actions offre 2000 minuti/mese nel free tier. Una scansione Trivy media richiede 2-3 minuti, quindi ~600+ scansioni/mese gratis.

Q: Trivy funziona solo con Docker?
No! Trivy scansiona anche: Kubernetes manifests, Terraform files, npm/pip/maven packages, filesystem, git repositories.

Q: Come gestisco i false positive?
Usa un file .trivyignore nella root del repository per ignorare CVE specifiche con motivazione documentata.

Q: Posso usare Trivy con altri CI/CD (GitLab, Jenkins)?
Assolutamente sì! Trivy ha integrazioni native per GitLab CI, Jenkins, CircleCI, Azure Pipelines e altri.

Q: Le scansioni rallentano il mio workflow?
Mediamente 2-3 minuti. Con cache ottimizzata: 30-60 secondi.

Q: Cosa succede se vengono trovate 500+ vulnerabilità?
Inizia filtrando solo CRITICAL/HIGH. Poi usa immagini base minimal (Alpine). Infine, valuta ogni CVE nel tuo contesto specifico.