Come leggere un report di CodeAuditAgent e agire di conseguenza

Un report di sicurezza è utile solo se si trasforma in correzioni rilasciate. I report di CodeAuditAgent sono pensati proprio per questo: ogni problema è abbastanza specifico da poter essere verificato in fretta e arriva con una patch che puoi adattare. Questa guida spiega ogni parte di un report, come fare triage quando non hai un security engineer dedicato e come confermare che le tue correzioni abbiano funzionato.

Che cosa viene analizzato

Un audit gira su un repository GitHub pubblico oppure su uno snippet di codice che incolli. Per i repository, CodeAuditAgent legge il branch predefinito. I repository privati non possono essere analizzati tramite URL, e non ci sono ancora commenti sulle pull request; i risultati vivono nella dashboard e negli export.

Quanta parte di un repository viene letta dipende dal tuo piano. Il piano gratuito copre 1 repository, 3 audit al mese e fino a 20 file per audit. Starter, a 49 $ al mese, copre 5 repository, 50 audit e 40 file per audit. Pro, a 199 $ al mese, copre repository illimitati, 500 audit e 80 file per audit. I singoli file più grandi di 60 KB vengono saltati. I conteggi mensili degli audit si azzerano all'inizio di ogni mese di calendario (UTC). Uno snippet incollato è anche un modo rapido per controllare un singolo file che ti preoccupa prima di analizzare l'intero repository.

Quando alcuni file restano fuori per via di questi limiti, il report viene etichettato come istantanea parziale. Prendi sul serio quell'etichetta. Un report parziale pulito significa che i file letti sembrano puliti, non che lo sia il repository. Se il codice che ti sta più a cuore è stato escluso, analizzalo come snippet incollato o su un piano che copra più file.

Il punteggio di rischio

In cima a ogni report c'è un punteggio di rischio da 0 a 100; l'export Markdown indica accanto anche la gravità complessiva. Più è alto, maggiore è il rischio. È una sintesi dei problemi di quell'audit, utile per due cose: decidere con quanta urgenza guardare un repository e monitorare se sta migliorando nel tempo.

Non dare troppo peso a piccole differenze tra repository non correlati. Un punteggio è sempre relativo a ciò che è stato analizzato, e un'istantanea parziale vede meno codice. È nel confronto dello stesso repository prima e dopo le correzioni che il numero è più significativo.

Gravità e confidenza

Ogni problema ha una gravità e una confidenza. Rispondono a domande diverse: la gravità indica quanto sarebbe grave se il problema fosse reale, la confidenza indica quanto chi ha revisionato è sicuro che lo sia.

• Critica: direttamente sfruttabile e con impatto serio, come un'injection su un endpoint pubblico, un bypass dell'autenticazione o credenziali di produzione esposte.
• Alta: una vulnerabilità reale che richiede qualche precondizione, oppure con impatto significativo ma limitato.
• Media: una debolezza che conta in combinazione con altri bug, oppure con impatto moderato.
• Bassa: questioni di hardening e lacune nella difesa in profondità.
• Informativa: osservazioni utili da conoscere che di per sé non sono vulnerabilità.

La confidenza è alta, media o bassa. Un problema ad alta confidenza ha prove chiare nel codice che è stato letto. Un problema a bassa confidenza dipende di solito da qualcosa che l'audit non poteva vedere, come un middleware in un altro file, una policy del database o un valore di configurazione impostato al momento del deploy. Bassa confidenza non vuol dire ignoralo: vuol dire che una persona dovrebbe verificare il contesto mancante prima di correggere.

Anatomia di un problema

Ogni problema segue la stessa struttura, così puoi verificarlo in un ordine coerente.

• Titolo e CWE: la classe di debolezza, per esempio CWE-639 per un bypass dell'autorizzazione tramite chiave controllata dall'utente. Il CWE ti dice che tipo di correzione aspettarti.
• Posizione: il file e la riga, così puoi aprire direttamente il codice.
• Prove: il codice rilevante citato dal file. Verifica che la citazione corrisponda al tuo codice attuale; se la riga è già cambiata, il problema potrebbe non essere più attuale.
• Scenario di exploit: come un attaccante userebbe concretamente la debolezza, passo per passo. È il modo più rapido per giudicare se sia reale nel tuo contesto.
• Patch di correzione: una modifica suggerita nello stile del codice circostante.

Considera la patch un ottimo punto di partenza, non un commit pronto per il merge. È scritta a partire dal codice che l'audit ha letto, quindi potrebbe non conoscere le tue funzioni di utilità, le tue convenzioni sull'ORM o un chiamante altrove nella codebase. Una patch tipica è piccola e mirata:

--- a/app/api/invoices/[id]/route.ts
+++ b/app/api/invoices/[id]/route.ts
@@
-  const invoice = await db.invoice.findUnique({ where: { id } });
+  const invoice = await db.invoice.findFirst({
+    where: { id, userId: session.user.id },
+  });
   if (!invoice) return Response.json({ error: 'not_found' }, { status: 404 });

Osservazioni positive e prossimi passi

I report elencano anche ciò che è fatto bene: query parametrizzate usate in modo coerente, segreti caricati dall'ambiente, una configurazione dei cookie rigorosa. Vale la pena leggerle. Ti dicono quali schemi mantenere e riportare nel nuovo codice, e sono utili quando devi spiegare a qualcun altro lo stato di una codebase.

La sezione dei prossimi passi consigliati trasforma i problemi in un piano ordinato. Spesso raggruppa problemi correlati, per esempio diversi controlli di proprietà mancanti che conviene correggere con un unico helper condiviso anziché con cinque patch separate.

Un flusso di triage per team piccoli

Senza un security engineer, il rischio non è ignorare un report; è passare una giornata su problemi di bassa gravità mentre uno critico aspetta. Un ordine semplice funziona bene:

• Leggi per primi tutti i problemi critici e alti. Per ciascuno, leggi lo scenario di exploit e decidi: reale, non reale, o serve altro contesto.
• Correggi in giornata i problemi critici reali. Se una correzione richiede tempo, aggiungi una mitigazione temporanea come disattivare l'endpoint o irrigidire un controllo.
• Per i problemi che richiedono contesto, verifica il pezzo mancante: esiste un middleware, una policy a livello di riga o una configurazione che già lo impedisce? Metti per iscritto la risposta.
• Pianifica i problemi alti nello sprint corrente, quelli medi nel backlog, e raggruppa quelli bassi e informativi in una sessione di hardening.
• Quando un problema non è reale, annota il perché. Quella nota eviterà alla prossima persona di indagare di nuovo.

Assegna ogni problema a un unico responsabile. I problemi condivisi da tutto il team tendono a non appartenere a nessuno.

L'esploratore dei problemi e gli export

Una volta che hai diversi audit, l'esploratore dei problemi è più comodo dei singoli report. Elenca i problemi di tutti gli audit e li filtra per gravità, CWE e repository. Filtrare per CWE è particolarmente utile: se la stessa debolezza compare in tre repository, di solito indica uno schema condiviso o un helper mancante, e correggere lo schema costa meno che correggere ogni singola occorrenza.

I problemi possono essere esportati in CSV dall'esploratore, comodo per importarli in un issue tracker o in un foglio di calcolo. I singoli report possono essere esportati in Markdown, che si legge bene nella descrizione di una pull request, in una wiki interna o in un messaggio a un collaboratore esterno che si occupa della correzione.

Ripeti l'audit per confermare la correzione

Una correzione non è conclusa finché non l'hai verificata. Dopo il merge, esegui un nuovo audit sullo stesso repository. Ogni report può essere confrontato con l'audit precedente, così puoi vedere quali problemi sono spariti, quali restano e se ne sono comparsi di nuovi. Il punteggio di rischio dovrebbe scendere quando i problemi reali vengono corretti; se non accade, guarda il confronto per capire perché.

Mantieni equo il confronto. Se il primo audit era un'istantanea parziale e il secondo ha letto file diversi, la differenza riflette la copertura oltre alle correzioni. Gli audit rientrano nella tua quota mensile, quindi di solito conviene raggruppare diverse correzioni prima di rieseguire l'audit anziché rilanciarlo dopo ogni commit.

Che cosa un report non copre

Conoscere i limiti aiuta a colmare le lacune. Gli audit leggono il tuo codice sorgente; non analizzano le dipendenze alla ricerca di versioni note come vulnerabili, quindi tieni attivo anche uno scanner delle dipendenze, come quello integrato nel tuo package manager o in GitHub. Gli audit non vedono la configurazione applicata al deploy, l'infrastruttura esterna al repository o i file che sono stati saltati. E come qualsiasi revisore, umano o IA, l'audit può sbagliare: le prove e i livelli di confidenza ci sono proprio perché tu possa verificarlo rapidamente anziché fidarti sulla parola.

Usato in questo modo, un report diventa un elenco breve e prioritizzato di modifiche con le prove allegate. Correggi quelli critici, verifica quelli incerti, ripeti l'audit e guarda il punteggio muoversi.