Skip to content
KitploitKITPLOIT
StrumentiBlog
Invia
StrumentiBlog
Invia

Strumenti di Hacking, PenTest e Cybersecurity per il tuo Arsenale di Sicurezza!

Kitploit è una directory di strumenti di hacking, cybersecurity e pentesting. Scopri gli ultimi aggiornamenti dei progetti per trovare vulnerabilità, analizzare sistemi, automatizzare i test e rafforzare la tua sicurezza.

··Feed·Contatto·Privacy·© 2026 Kitploit

Directory degli strumenti

Categorie

Vedi tutte le categorie
Loading categories
Vulnhalla — Pipeline automatizzata di analisi della sicurezza che esegue query CodeQL sui repository GitHub e utilizza LLM per classificare e filtrare le vulnerabilità reali dai falsi positivi. | Kitploit
Strumenti/GitHubGitHub/cyberark/vulnhalla
Analisi StaticaAnalisi delle VulnerabilitàAnalisi del CodiceDevSecOpsMachine LearningApprendimento e FormazioneSicurezza dell'IA
GitHubcyberark/vulnhalla

Vulnhalla

Pipeline automatizzata di analisi della sicurezza che esegue query CodeQL sui repository GitHub e utilizza LLM per classificare e filtrare le vulnerabilità reali dai falsi positivi.

Vedi Repository
20141491 mese faRevisionato da Kitploit

Più Popolari

Vedi tutti →

Scopri gli strumenti più utilizzati dalla nostra community.

Esplora tutti gli strumenti

Sfoglia la nostra collezione di strumenti

Vedi tutti gli strumenti →
Condividi

Vulnhalla

Analisi CodeQL automatizzata con classificazione LLM

Vulnhalla

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:
root@kitploit:~
git clone https://github.com/cyberark/Vulnhalla
cd Vulnhalla
  1. Copia .env.example in .env:
root@kitploit:~
cp .env.example .env # macOS / Linux
Copy-Item .env.example .env # Windows (PowerShell)
  1. Modifica .env e inserisci i tuoi valori:

Esempio per OpenAI:

root@kitploit:~
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):

root@kitploit:~
# 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:

root@kitploit:~
# 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):

root@kitploit:~
# 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:

root@kitploit:~
# 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

root@kitploit:~
# 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):

root@kitploit:~
poetry run vulnhalla --local C:\percorso\al\mio-database-codeql

macOS / Linux:

root@kitploit:~
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

root@kitploit:~
# 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

root@kitploit:~
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

  • ↑/↓ - Navigare l'elenco dei problemi (riga per riga)
  • Tab / Shift+Tab - Cambiare focus tra i pannelli
  • Enter - Mostrare i dettagli per il problema selezionato
  • / - Focalizzare la casella di ricerca (nel pannello sinistro)
  • Esc - Cancellare la ricerca e riportare il focus sulla tabella dei problemi
  • r - Ricaricare i risultati dal disco
  • [ / ] - Ridimensionare i pannelli sinistro/destro (regolare la posizione dello split)
  • q - Uscire dall'applicazione

Funzionalità interattive

Ordinamento colonne

  • Fare clic su qualsiasi intestazione di colonna per ordinare per quella colonna
  • Ordinamento predefinito: per Repo (crescente), poi per ID (crescente)

Pannelli ridimensionabili

  • Divisore trascinabile tra i pannelli Elenco problemi e Dettagli
  • Mouse: Fare clic e trascinare il divisore per ridimensionare
  • Tastiera: Usare [ per spostare il divisore a sinistra, ] per spostarlo a destra
  • La posizione dello split viene ricordata durante la sessione

📊 Struttura dell'output

Dopo aver eseguito la pipeline, i risultati sono organizzati in output/results/<LANG>/<ISSUE_TYPE>/:

root@kitploit:~
output/results/c/Copy_function_using_source_size/
├── 1_raw.json      # Dati originali del problema CodeQL
├── 1_final.json    # Conversazione e classificazione LLM
├── 2_raw.json
├── 2_final.json
└── ...

Ogni *_final.json contiene:

  • Conversazione LLM completa (prompt di sistema, messaggi utente, risposte assistente, chiamate strumenti)
  • Codice di stato finale (1337 = vulnerabile, 1007 = sicuro, 7331/3713 = necessita più informazioni)

Ogni *_raw.json contiene:

  • Dati originali del problema CodeQL
  • Contesto della funzione
  • Percorso del database (include informazioni org/repo: output/databases/<LANG>/<ORG>/<REPO>)
  • Posizione del problema

🛠 Risoluzione dei problemi

  • CodeQL CLI non trovato: Imposta CODEQL_PATH nel tuo file .env con il percorso completo dell'eseguibile CodeQL. Su Windows: Il percorso deve terminare con .cmd (es. C:\percorso\per\codeql\codeql.cmd).

  • Limiti di velocità GitHub: Imposta GITHUB_TOKEN nel tuo file .env (ottieni il token da https://github.com/settings/tokens).

  • Problemi con LLM: Controlla che le tue chiavi API nel file .env corrispondano al provider selezionato.

  • Errori di import nell'interfaccia utente: Assicurati di eseguire dalla directory principale del progetto, oppure usa python examples/ui_example.py che gestisce l'impostazione del percorso.

⚙️ Riferimento configurazione

Variabili d'ambiente

Tutta la configurazione è gestita tramite variabili d'ambiente nel file .env. Ecco un riferimento completo:

Variabili obbligatorie

VariabileRichiesta perDescrizione
CODEQL_PATHTuttiPercorso dell'eseguibile CodeQL. Predefinito a codeql se CodeQL è nel PATH. Usa il percorso completo se non è nel PATH (es. C:\percorso\per\codeql\codeql.cmd su Windows)
PROVIDERTuttiProvider LLM: openai, azure, gemini, bedrock, anthropic, mistral, groq, openrouter, ollama, ecc.
MODELTuttiNome del modello (es. gpt-4o, gpt-4-turbo, gemini-2.5-flash)

Variabili obbligatorie specifiche per provider

OpenAI:

VariabileDescrizione
OPENAI_API_KEYLa tua chiave API OpenAI da platform.openai.com

Azure OpenAI:

VariabileDescrizione
AZURE_OPENAI_API_KEY o AZURE_API_KEYLa tua chiave API Azure OpenAI
AZURE_OPENAI_ENDPOINT o AZURE_API_BASEL'URL dell'endpoint Azure OpenAI (es. https://tuo-risorsa.openai.azure.com)
AZURE_OPENAI_API_VERSION o AZURE_API_VERSIONVersione API (predefinita: 2024-08-01-preview)

Gemini (Google):

VariabileDescrizione
GOOGLE_API_KEYLa tua chiave API Google da Google AI Studio

AWS Bedrock:

VariabileObbligatoriaDescrizione
AWS_REGION_NAMESìRegione AWS (es. us-east-1, us-west-2)
AWS_PROFILENo*Nome del profilo AWS per autenticazione SSO/file credenziali
AWS_ACCESS_KEY_IDNo*Chiave di accesso AWS (se non si usa il profilo)
AWS_SECRET_ACCESS_KEYNo*Chiave segreta AWS (se non si usa il profilo)
AWS_SESSION_TOKENNoToken di sessione per credenziali STS temporanee

* Autenticazione: Usa AWS_PROFILE oppure AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (+ opzionale AWS_SESSION_TOKEN per STS).

Esempio .env per Bedrock (SSO):

root@kitploit:~
PROVIDER=bedrock
MODEL=anthropic.claude-3-5-sonnet-20241022-v2:0
AWS_REGION_NAME=us-east-1
AWS_PROFILE=tuo-profilo

⚠️ Prerequisiti:

  • Le credenziali AWS devono essere configurate (SSO, profilo IAM o chiavi di accesso) con autorizzazioni per invocare i modelli Bedrock
  • Per utenti SSO: Esegui aws sso login --profile tuo-profilo prima di utilizzare Vulnhalla

🔧 Importante - Selezione del modello: Quando selezioni un modello Bedrock, assicurati che supporti il tool calling/function calling (non tutti i modelli Bedrock lo fanno). Il tool calling è una parte chiave del flusso di analisi di Vulnhalla, quindi scegliere un modello compatibile fa una grande differenza in termini di funzionalità e risultati. I modelli compatibili includono: Claude 3.x, Mistral, o Cohere Command R.

Variabili opzionali

VariabilePredefinitoDescrizione
GITHUB_TOKEN-Token API GitHub per limiti di velocità più elevati. Ottienilo da GitHub Settings > Tokens
GITHUB_API_URLhttps://api.github.comURL API GitHub. Per GitHub Enterprise, imposta l'URL API del tuo server (es. https://github.tua-azienda.com/api/v3)
GITHUB_SSL_VERIFYtrueVerifica certificato SSL. Imposta a false per GitHub Enterprise con certificati autofirmati o CA interni
LLM_TEMPERATURE0.2Temperatura LLM (0.0-2.0). Più basso = più deterministico. Consigliato: mantenerlo a 0.2
LLM_TOP_P0.2Campionamento top-p LLM (0.0-1.0). Più basso = più focalizzato. Consigliato: mantenerlo a 0.2
LOG_LEVELINFOLivello di logging: DEBUG, INFO, WARNING, o ERROR. Controlla la verbosità dell'output console
LOG_FILE-Percorso opzionale al file di log (es. logs/vulnhalla.log). Se impostato, i log vengono scritti sia su console che su file. Il logging su file usa livello DEBUG per output dettagliato
LOG_FORMATdefaultStile formato log: default (leggibile dall'uomo), o json (formato JSON strutturato)
LOG_VERBOSE_CONSOLEfalseSe true, WARNING/ERROR/CRITICAL usano formato completo (timestamp - logger - livello - messaggio). Predefinito: WARNING/ERROR usano formato semplice (LEVEL - messaggio), INFO sempre minimale (solo messaggio)
THIRD_PARTY_LOG_LEVELERRORLivello log per librerie di terze parti (LiteLLM, urllib3, requests). Opzioni: , , , . Predefinito sopprime la maggior parte del rumore di terze parti

⚠️ Importante: Non aumentare LLM_TEMPERATURE o LLM_TOP_P a meno che tu non capisca appieno l'impatto. Valori più bassi mantengono il modello stabile e deterministico, il che è fondamentale per l'analisi della sicurezza. Valori più alti potrebbero portare il modello a diventare incoerente, creativo o a allucinare risultati.

📝 Nota: Per ulteriori esempi di configurazione, consulta il file .env.example nella radice del progetto.

Convalida della configurazione

Vulnhalla convalida la tua configurazione all'avvio. Se mancano variabili obbligatorie o non sono valide, vedrai chiari messaggi di errore che indicano cosa deve essere corretto.

Errori di convalida comuni:

  • Chiave API mancante per il provider selezionato
  • Nome provider non valido (vedi PROVIDER per i valori supportati)
  • Endpoint Azure mancante (richiesto per provider Azure)
  • Credenziali o regione AWS mancanti (richiesti per provider Bedrock)
  • Percorso CodeQL non valido (se CODEQL_PATH è impostato ma il file non esiste)

📝 Codici di stato

L'LLM utilizza i seguenti codici di stato:

  • 1337: Vulnerabilità di sicurezza trovata (True Positive)
  • 1007: Il codice è sicuro, nessuna vulnerabilità (False Positive)
  • 7331: Necessario più codice/informazioni per convalidare la sicurezza
  • 3713: Probabilmente non è un problema di sicurezza, ma sono necessarie più informazioni (usato con 7331)

L'interfaccia utente li mappa come:

  • 1337 → "True Positive"
  • 1007 → "False Positive"
  • 7331 o 3713 → "Needs More Data"

🔧 Sviluppo

Esecuzione dei test

Il progetto include un'infrastruttura di test di base che utilizza pytest:

root@kitploit:~
# Esegui tutti i test
poetry run pytest

# Esegui con output verbose
poetry run pytest -v

La suite di test include smoke test per verificare che l'infrastruttura di test sia configurata correttamente.

Type Checking

Il progetto utilizza mypy per il type checking statico:

root@kitploit:~
poetry run mypy src

Il type checking è configurato in pyproject.toml sotto [tool.mypy]. La configurazione utilizza una baseline conservativa con override per modulo per consentire un'adozione graduale.

Dipendenze del progetto

Le dipendenze sono gestite tramite Poetry in pyproject.toml:

  • requests - Richieste HTTP per l'API GitHub
  • pySmartDL - Download manager intelligente per database CodeQL
  • litellm - Interfaccia LLM unificata che supporta più provider
  • python-dotenv - Gestione delle variabili d'ambiente
  • PyYAML - Analisi YAML per file pack CodeQL
  • textual - Framework per interfaccia utente a terminale
  • pytest - Framework di test (dipendenza di sviluppo)
  • mypy - Type checker statico (dipendenza di sviluppo)

Query CodeQL

Le query CodeQL sono organizzate in data/queries/<LANG>/:

  • issues/ - Query di rilevamento problemi di sicurezza
  • tools/ - Query helper (alberi di funzioni, classi, variabili globali, macro)

Ogni directory contiene un file qlpack.yml che definisce il pack CodeQL.

📄 Licenza

Copyright (c) 2025 CyberArk Software Ltd. Tutti i diritti riservati.

Questo repository è concesso in licenza sotto la Apache License, Version 2.0 - vedi LICENSE.txt per maggiori dettagli.

🤝 Contribuire

Accogliamo contributi di ogni tipo a questo repository. Per istruzioni su come iniziare e descrizioni dei nostri flussi di lavoro di sviluppo, consulta la nostra guida per contribuire.

Codice di condotta

Leggi e segui il nostro Codice di condotta. Siamo impegnati a fornire un ambiente accogliente e inclusivo per tutti i contributori.

📧 Contatti

Sentiti libero di contattarci tramite GitHub issues se hai richieste di funzionalità o problemi con il progetto.

Scarica lo strumento
DEBUG
INFO
WARNING
ERROR