Esportazione SARIF e integrazione con GitHub code scanning

Esporta un audit di vetkit completato tramite il suo endpoint dei report con format=sarif, poi carica il file SARIF 2.1.0 dal tuo workflow di GitHub Actions. Prima del caricamento, fai corrispondere l’audit al repository e al commit analizzati. Scaricare il report non pubblica di per sé alert su GitHub; il caricamento è un passaggio separato che configuri tu.

1. Verifica i prerequisiti

• Procurati l’ID dell’organizzazione, l’ID dell’audit e una chiave API di vetkit con reports:read. Un workflow automatico che avvia e interroga anche gli audit richiede audits:write e audits:read.
• Conferma repository e SHA del commit dell’audit. In CI, richiedi o riutilizza un audit per il commit esatto del workflow e attendi che sia completato prima di esportarlo.
• Controlla nel report JSON eventuali risultati parziali e il perimetro effettivo della scansione. Un documento SARIF valido può comunque rappresentare un’analisi incompleta.

GitHub supporta il code scanning per i repository pubblici e per i repository delle organizzazioni idonee con GitHub Code Security attivo. Verifica l’idoneità del tuo repository e i permessi di scrittura nella documentazione di GitHub sul caricamento dei file SARIF.

2. Esporta l’audit

Imposta le variabili qui sotto nella tua shell locale o nell’ambiente di CI. VETKIT_API_URL è l’origin dell’API di vetkit senza /v1. Conserva la chiave in un secret manager o in un secret della CI, non nel file del workflow, nel repository o in uno script di shell. Questo comando richiede curl e jq:

$ set -euo pipefail$ : "${VETKIT_API_URL:?Set the API origin}"$ : "${VETKIT_ORG_ID:?Set the organization ID}"$ : "${VETKIT_AUDIT_ID:?Set the completed audit ID}"$ : "${VETKIT_API_KEY:?Set a reports:read key}" $ curl --fail-with-body --silent --show-error --max-time 30 \  "$VETKIT_API_URL/v1/orgs/$VETKIT_ORG_ID/audits/$VETKIT_AUDIT_ID/report?format=sarif" \  -H "Authorization: Bearer $VETKIT_API_KEY" \  -o vetkit.sarif$ jq -e '.version == "2.1.0" and (.runs | type == "array")' vetkit.sarif >/dev/null

L’endpoint restituisce application/sarif+json e un nome file per l’allegato basato sul commit sottoposto ad audit. Il comando lo salva di proposito come vetkit.sarif per il passaggio di caricamento. Il controllo con jq è una verifica di formato di base, non una validazione completa dello schema né una conferma della completezza della scansione. Tratta il report scaricato come informazione sul repository e controllane l’accesso.

3. Carica dal tuo workflow

In un workflow del repository scansionato, fai il checkout del sorgente corrispondente, ottieni l’audit completato ed esegui il comando di download visto sopra. Tieni VETKIT_API_KEY in un secret di Actions. Il frammento seguente mostra i permessi e il passaggio finale di caricamento; non è un workflow di scansione autonomo. Aggiungi il download tra checkout e caricamento:

permissions:  contents: read  actions: read  security-events: write # Inside the job's steps, after choosing the matching audit:steps:  - uses: actions/checkout@v6    with:      persist-credentials: false  # Insert the authenticated download step here.  - name: Upload vetkit results    uses: github/codeql-action/upload-sarif@v4    with:      sarif_file: vetkit.sarif      category: vetkit

L’action di caricamento di GitHub usa sarif_file per il percorso del report e category per distinguere le analisi. Riutilizzare una coppia tool/categoria per lo stesso commit può sostituire i risultati precedenti; usa categorie distinte per analisi separate. I permessi e le versioni delle action qui sopra seguono l’esempio di GitHub.

L’esempio di integrazione del repository di vetkit mantiene opzionale il caricamento SARIF dietro VETKIT_UPLOAD_SARIF=true. Il suo workflow di scansione completa richiede un audit sul commit esatto e scarta i risultati falliti, parziali o senza punteggio prima del caricamento opzionale. Quel controllo di completamento non impone una soglia di gravità dei risultati o di punteggio: definisci a parte la tua policy di rilascio. I check della GitHub App e il caricamento SARIF sono percorsi di integrazione separati.

4. Interpreta i risultati importati

vetkit esporta una singola run SARIF con vetkit come driver. I risultati includono ID delle regole, posizioni nei file dove disponibili, testo di remediation e fingerprint di vetkit. Le versioni degli analizzatori sono registrate come estensioni, e la provenienza (repository/commit) è inclusa. La mappatura della gravità usa i livelli SARIF insieme alle proprietà di gravità di vetkit; queste mappature numeriche non sono punteggi CVSS calcolati in modo indipendente.

I risultati a livello di repository usano una posizione sintetica (repository), quindi potrebbero non puntare a una riga reale del sorgente. I risultati soppressi restano nell’esportazione con i metadati di soppressione SARIF. Non dare per scontato che il numero di risultati esportati coincida con il numero di alert attivi mostrati da GitHub. Conserva il report originale di vetkit per la copertura, il contesto del punteggio e i dettagli della revisione.

Risoluzione dei problemi

• Il download fallisce: controlla l’origin dell’API, gli ID di organizzazione e audit, la validità della chiave e lo scope reports:read. Non stampare la chiave durante il debug.
• Posizioni nel sorgente errate: confronta il commit dell’audit con il commit e il checkout del workflow. Non caricare un report più vecchio come evidenza per una revisione più recente.
• Il caricamento viene rifiutato: controlla l’idoneità su GitHub, i permessi del workflow e l’output di errore dell’action di caricamento. GitHub applica le proprie proprietà SARIF supportate e i propri limiti di dimensione.
• Nessun alert visibile: esamina i risultati del file, i metadati di soppressione, l’analisi selezionata e la copertura dell’audit originale. Un trasferimento riuscito non prova che la scansione sia pulita.

Fonti e limiti

Verificato il 1º novembre 2026 sul controller/service dei report di vetkit, sul serializzatore SARIF e sull’esempio di integrazione con GitHub Actions del repository. Consulta il riferimento dell’API e i requisiti di caricamento di GitHub per i due lati dell’integrazione. L’idoneità su GitHub e il comportamento delle action possono cambiare. L’esportazione SARIF trasferisce risultati esistenti; non esegue CodeQL, non aggiunge controlli all’audit originale e non garantisce che ogni dettaglio del report di vetkit compaia nell’interfaccia di GitHub.