Vulnhalla

Analisi CodeQL automatizzata con classificazione LLM

Per una panoramica dettagliata della ricerca e della motivazione alla base di Vulnhalla, consulta il post ufficiale del blog CyberArk Threat Research:

Vulnhalla: Picking the True Vulnerabilities from the CodeQL Haystack

Vulnhalla automatizza l'intera pipeline di analisi della sicurezza:

1. Recupero dei repository di un dato linguaggio di programmazione da GitHub
2. Download dei corrispondenti database CodeQL (se disponibili)
3. Esecuzione delle query CodeQL su tali database per rilevare problemi di sicurezza o qualità del codice
4. Post-elaborazione dei risultati con un LLM (ChatGPT, Gemini, ecc.) per classificare e filtrare i problemi

---

🚀 Avvio rapido

Passo 1: Prerequisiti

Prima di iniziare, assicurati di avere:

• Python 3.10 – 3.13 (Python 3.11 o 3.12 raccomandato)

  • Python 3.14+ non è supportato (questo strumento utilizza grpcio che non è supportato da Python 3.14+)
  • Scarica da python.org

• CodeQL CLI

  • Scarica da CodeQL CLI releases
  • Assicurati che codeql sia nel tuo PATH, oppure imposterai il percorso in .env (vedi Passo 2)

• (Opzionale) Token API GitHub

  • Per limiti di velocità più elevati durante il download dei database
  • Ottienilo da GitHub Settings > Tokens

• Chiave API LLM

  • Credenziali OpenAI, Azure, Gemini o Bedrock (a seconda del provider)

Passo 2: Configurare l'ambiente

Tutta la configurazione è in un unico file: .env

1. Clona il repository:

git clone https://github.com/cyberark/Vulnhalla
cd Vulnhalla

2. Copia .env.example in .env:

cp .env.example .env # macOS / Linux
Copy-Item .env.example .env # Windows (PowerShell)

3. Modifica .env e inserisci i tuoi valori:

Esempio per OpenAI:

CODEQL_PATH=codeql
GITHUB_TOKEN=ghp_your_token_here
PROVIDER=openai
MODEL=gpt-4o
OPENAI_API_KEY=your-api-key-here
LLM_TEMPERATURE=0.2
LLM_TOP_P=0.2

# Opzionale: Configurazione logging
LOG_LEVEL=INFO                  # DEBUG, INFO, WARNING, ERROR
LOG_FILE=                       # Opzionale: percorso file di log (es. logs/vulnhalla.log)
LOG_FORMAT=default              # default o json
# LOG_VERBOSE_CONSOLE=false     # Se true, WARNING/ERROR usano formato completo (timestamp - logger - livello - messaggio)

📖 Per il riferimento completo alla configurazione: Vedi Riferimento configurazione qui sotto per tutti i provider supportati (OpenAI, Azure, Gemini, Bedrock), variabili obbligatorie/opzionali ed esempi dettagliati.

Passo 3: Installare Poetry (Raccomandato: pipx)

Windows (PowerShell):

# Elenca le versioni Python disponibili
py -0p

# Scegli un Python supportato: 3.10 / 3.11 / 3.12 / 3.13
py -3.12 -m pip install --user -U pipx
py -3.12 -m pipx ensurepath
# Chiudi e riapri il terminale (obbligatorio)
pipx install poetry
poetry --version

macOS / Linux:

# Controlla la tua versione Python
python3 --version

# Usa qualsiasi Python supportato: 3.10 / 3.11 / 3.12 / 3.13
python3 -m pip install --user -U pipx
python3 -m pipx ensurepath
# Riavvia il terminale (obbligatorio)
pipx install poetry
poetry --version

Passo 4: Installare le dipendenze e configurare

Windows (PowerShell):

# Scegli una versione supportata che hai: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # Forza Poetry a usare una versione Python supportata se hai più versioni installate
poetry install
poetry run vulnhalla-setup

macOS / Linux:

# Scegli una versione supportata che hai: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # Forza Poetry a usare una versione Python supportata se hai più versioni installate
poetry install
poetry run vulnhalla-setup

Passo 5: Eseguire la pipeline

# Analizza un repository specifico, ad esempio:
poetry run vulnhalla redis/redis

# Scarica di nuovo anche se il database esiste già
poetry run vulnhalla redis/redis --force

# Mostra aiuto
poetry run vulnhalla --help

Questo farà automaticamente:

1. Recuperare i database CodeQL
2. Eseguire le query CodeQL su tutti i database scaricati
3. Analizzare i risultati con LLM e salvarli in output/results/
4. Aprire l'interfaccia utente per navigare tra i risultati

Utilizzare un database CodeQL locale

Se hai già un database CodeQL su disco (ad esempio creato manualmente o da un'esecuzione precedente), puoi saltare il passaggio di recupero da GitHub usando il flag --local / -l:

Windows (PowerShell):

poetry run vulnhalla --local C:\percorso\al\mio-database-codeql

macOS / Linux:

poetry run vulnhalla --local /percorso/al/mio-database-codeql

Nota: Il flag --local richiede una directory di database CodeQL, non una cartella di codice sorgente. Puoi verificare controllando che la cartella contenga un file codeql-database.yml.

Comandi aggiuntivi

# Aprire l'interfaccia utente per visualizzare i risultati esistenti (senza eseguire l'analisi)
poetry run vulnhalla-ui

# Convalidare la configurazione: CodeQL, LLM, Logging (senza eseguire l'analisi)
poetry run vulnhalla-validate

# Elencare i repository analizzati e i conteggi dei problemi
poetry run vulnhalla-list

# Eseguire la pipeline di esempio (analizza videolan/vlc e redis/redis)
poetry run vulnhalla-example

---

🖥️ Interfaccia Utente (UI)

Vulnhalla include un'interfaccia utente completa per navigare ed esplorare i risultati dell'analisi.

Esecuzione dell'interfaccia utente

poetry run vulnhalla-ui

Layout dell'interfaccia utente

L'interfaccia mostra un'area superiore a due pannelli con una barra dei controlli in basso:

Area superiore (affiancata, ridimensionabile):

• Pannello sinistro (Elenco problemi):

  • DataTable che mostra: ID, Repo, Nome problema, File, Decisione LLM, Decisione manuale
  • Conteggio problemi e indicatore di ordinamento
  • Casella di ricerca in basso, si aggiorna mentre si digita (senza distinzione tra maiuscole e minuscole).

• Pannello destro (Dettagli):

  • Sezione Decisione LLM: Mostra la classificazione dell'LLM (True Positive, False Positive, o Needs More Data)
  • Sezione Metadati: Nome problema, Repo, File, Riga, Tipo, Nome funzione
  • Sezione Codice:
    • 📌 Contesto iniziale del codice (primo snippet di codice visto dall'LLM)
    • 📥 Codice aggiuntivo (codice richiesto dall'LLM durante la conversazione) - mostrato solo se esiste codice aggiuntivo
    • Riga vulnerabile evidenziata in rosso
  • Sezione Riepilogo: Risposta/decisione finale dell'LLM
  • Selezione decisione manuale: Menu a tendina in basso per impostare il verdetto manuale (True Positive, False Positive, Uncertain, o Not Set)

Barra dei controlli in basso:

• Lingua: C (unica lingua attualmente supportata)
• Filtro per decisione LLM a tendina: All, True Positive, False Positive, Needs more Info to decide
• Pulsanti azione: Refresh, Run Analysis
• Testo di aiuto per i tasti

Combinazioni di tasti