VulTriage

Un framework intelligente per il rilevamento delle vulnerabilità basato su modelli linguistici di grandi dimensioni e analisi statica del codice, con supporto per la valutazione su più dataset e studi di ablazione.

📋 Indice

• Introduzione
• Caratteristiche Principali
• Requisiti di Sistema
• Avvio Rapido
• Utilizzo
• Dataset e Modelli
• FAQ

Introduzione

Questo progetto è un framework intelligente per il rilevamento delle vulnerabilità basato sui modelli GPT-4o e BGE-M3, che combina:

• Analisi della Struttura Statica: Control Flow Graphs (CFG), Data Flow Graphs (DFG), Abstract Syntax Trees (AST)
• Retrieval-Augmented Generation (RAG): corrispondenza di pattern di vulnerabilità basata sulla base di conoscenza CWE
• Comprensione del Codice: analisi semantica mediante modelli linguistici di grandi dimensioni
• Rilevamento a Coppie/Campione Singolo: supporto per più modalità di valutazione

Caratteristiche Principali

• ✅ Supporto per i dataset PrimeVul e Kotlin
• ✅ Recupero integrato dalla base di conoscenza delle vulnerabilità CWE
• ✅ Studi di ablazione configurabili
• ✅ Monitoraggio delle metriche in tempo reale
• ✅ Supporto flessibile per esperimenti sugli iperparametri

Requisiti di Sistema

• Python >= 3.9
• CUDA (opzionale, per l'accelerazione GPU)

Avvio Rapido

1. Installare le Dipendenze

pip install -r requirements.txt

2. Preparare le Risorse

Scaricare il Modello BGE-M3

Il modello verrà scaricato automaticamente, oppure puoi scaricarlo manualmente:

git clone https://huggingface.co/BAAI/bge-m3
# Note: BGE-M3 related dependencies can be installed via FlagEmbedding. For details, refer to: pip install -U FlagEmbedding

Preparare i Dati CWE

Assicurati che i file cwec_latest.xml/cwec_v4.19.1.xml e 1435.csv/1435_filtered_columns.csv (dati dell'indice CWE) esistano nella directory principale del progetto.

Nota: Questo progetto utilizza le CWE Top 25 Most Dangerous Software Weaknesses. I file correlati sono già inclusi nella directory principale del progetto.

Preparare i Dataset

Posiziona i seguenti file nella directory principale del progetto:

• primevul_test_paired.jsonl (dataset PrimeVul)
• LLM4Vul-main/LLM4Vul-main/data/kotlin_data.csv (dataset Kotlin)

3. Configurare la Chiave API

Modifica la configurazione API OpenAI in main.py o hyperparam_exp.py:

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://api.poixe.com/v1"
)

Nota: l'URL corrente https://api.poixe.com/v1 non è stato analizzato correttamente. Potrebbe essere un tipo di pagina web non supportato o un collegamento interrotto. Verifica la validità del collegamento oppure passa a un altro provider API.

4. Eseguire il Rilevamento delle Vulnerabilità

Modalità Base (Funzionalità Completa)

python main.py --wotask all --jsonl_file primevul_test_paired.jsonl

Modalità Studio di Ablazione

# Without control flow information
python main.py --wotask wo_ctrl_info_pth --jsonl_file primevul_test_paired.jsonl
# Without RAG knowledge
python main.py --wotask wo_rag_pth --jsonl_file primevul_test_paired.jsonl
# Without code understanding
python main.py --wotask wo_exp_pth --jsonl_file primevul_test_paired.jsonl
# Without any auxiliary information
python main.py --wotask nan --jsonl_file primevul_test_paired.jsonl

Esperimenti sugli Iperparametri

# Pairwise evaluation mode
python hyperparam_exp.py --mode pairwise --input_file primevul_test_paired.jsonl --detail_level C --info_comb all --desc_level concise --max_vuln 2
# Single-sample evaluation mode
python hyperparam_exp.py --mode single --input_file LLM4Vul-main/LLM4Vul-main/data/kotlin_data.csv

5. Visualizzare i Risultati

I risultati del rilevamento vengono salvati in tempo reale in metrics_log.txt e i riepiloghi finali della valutazione vengono stampati sul terminale:

• Le metriche di valutazione includono accuratezza, richiamo, tasso di falsi positivi, ecc.
• I risultati degli studi di ablazione confrontano le differenze di prestazione tra le diverse modalità per analizzare il contributo di ciascun modulo.

Utilizzo

Panoramica degli Script Principali

Descrizione dei Parametri

Parametri di main.py

Parametri di hyperparam_exp.py

Dataset e Modelli

📊 Dataset

1. Dataset PrimeVul

• Citazione: Yangruibo Ding, Yanjun Fu, Omniyyah Ibrahim, Chawin Sitawarin, Xinyun Chen, Basel Alomair, David Wagner, Baishakhi Ray, and Yizheng Chen. 2025. Vulnerability detection with code language models: How far are we? ISSTA 2025 (2025).
• Scopo: benchmark di rilevamento delle vulnerabilità a coppie
• Formato: JSONL (contiene i campi func e target)
• Fonte: Conferenza ISSTA 2025 (Sito ufficiale ISSTA). Fare riferimento all'articolo originale per i permessi di accesso al dataset.

2. Dataset Kotlin

• Citazione: Triet Huynh Minh Le, M Ali Babar, and Tung Hoang Thai. 2024. Software vulnerability prediction in low-resource languages: An empirical study of codebert and chatgpt. In Proceedings of the 28th International Conference on Evaluation and Assessment in Software Engineering, 679–685.
• Scopo: ricerca sulla previsione delle vulnerabilità in lingue a basse risorse
• Formato: CSV (contiene le colonne code e label)
• Fonte: Conferenza EASE 2024 (Sito ufficiale EASE 2024). Fare riferimento all'articolo originale per i permessi di accesso al dataset.

3. Database CWE

• Versione: CWE v4.19.1
• Fonte: MITRE CWE
• Scopo: base di conoscenza di pattern di vulnerabilità e potenziamento del recupero
• Nota: CWE può essere utilizzata liberamente per scopi di ricerca, sviluppo e commerciali. Deve essere mantenuta l'attribuzione del copyright a MITRE.

🤖 Modelli

1. Modello di Embedding BGE-M3

• Sviluppatore: BAAI (Beijing Academy of Artificial Intelligence)
• HuggingFace: BAAI/bge-m3
• Licenza: Licenza MIT (Nota: l'analisi della pagina della licenza del modello corrente non è riuscita. Fare riferimento alla licenza del progetto FlagEmbedding, che è la Licenza MIT)
• Scopo: recupero ibrido con vettori densi e sparsi, supporto a recupero multilingue, multi-granularità (lunghezza massima di input 8192 token) e multifunzionale
• Progetto correlato: FlagEmbedding (repository open-source per i modelli della serie BGE)

2. GPT-4o

• Sviluppatore: OpenAI
• Versione del Modello: gpt-4o-2024-11-20
• Licenza: Segue i Termini di utilizzo di OpenAI (in vigore dal 1 gennaio 2026)
• Scopo: comprensione del codice, identificazione delle vulnerabilità, ragionamento e giudizio
• Nota: L'utilizzo deve essere conforme ai Termini di servizio di OpenAI. Sono proibite attività illegali o dannose e l'ingegneria inversa del modello.

📦 Librerie di Dipendenze

FAQ

Q1: Come cambiare il provider API OpenAI?

Modifica base_url e api_key in main.py o hyperparam_exp.py.

Q2: Perché i risultati del recupero non sono accurati?

1. Controlla se 1435.csv/1435_filtered_columns.csv viene caricato correttamente e assicurati che il formato dei dati dell'indice CWE sia corretto;
2. Conferma che il modello BGE-M3 sia stato scaricato correttamente. Puoi scaricarlo manualmente tramite git clone https://huggingface.co/BAAI/bge-m3;

Q3: Come personalizzare le metriche di valutazione?

Modifica il metodo update_pair_metrics in metrics_tracker.py per aggiungere o regolare la logica di calcolo delle metriche.

Q4: Cosa fare se il download del modello BGE-M3 fallisce?

Scarica i file del modello direttamente dal sito web di HuggingFace, estraili nella directory principale del progetto, oppure verifica la connessione di rete e riesegui il comando git clone https://huggingface.co/BAAI/bge-m3.