Vulnhalla

Analyse CodeQL automatisée avec classification par LLM

Pour un aperçu détaillé de la recherche et de la motivation derrière Vulnhalla, consultez l'article de blog officiel de CyberArk Threat Research :

Vulnhalla : Extraire les vraies vulnérabilités de la botte de foin CodeQL

Vulnhalla automatise l'ensemble du pipeline d'analyse de sécurité :

1. Récupération des dépôts d'un langage de programmation donné depuis GitHub
2. Téléchargement de leurs bases de données CodeQL correspondantes (si disponibles)
3. Exécution des requêtes CodeQL sur ces bases de données pour détecter des problèmes de sécurité ou de qualité de code
4. Post-traitement des résultats avec un LLM (ChatGPT, Gemini, etc.) pour classer et filtrer les problèmes

---

🚀 Démarrage rapide

Étape 1 : Prérequis

Avant de commencer, assurez-vous de disposer de :

• Python 3.10 – 3.13 (Python 3.11 ou 3.12 recommandé)

  • Python 3.14+ n'est pas pris en charge (cet outil utilise grpcio qui n'est pas pris en charge par Python 3.14+)
  • Téléchargement depuis python.org

• CodeQL CLI

  • Téléchargement depuis les versions de CodeQL CLI
  • Assurez-vous que codeql est dans votre PATH, ou vous définirez le chemin dans .env (voir l'étape 2)

• (Facultatif) Jeton API GitHub

  • Pour des limites de débit plus élevées lors du téléchargement des bases de données
  • Obtenez-le depuis Paramètres GitHub > Jetons

• Clé API LLM

  • Identifiants OpenAI, Azure, Gemini ou Bedrock (selon votre fournisseur)

Étape 2 : Configuration de l'environnement

Toute la configuration se trouve dans un seul fichier : .env

1. Clonez le dépôt :

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

2. Copiez .env.example vers .env :

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

3. Modifiez .env et renseignez vos valeurs :

Exemple pour 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

# Optional: Logging Configuration
LOG_LEVEL=INFO                  # DEBUG, INFO, WARNING, ERROR
LOG_FILE=                       # Optional: path to log file (e.g., logs/vulnhalla.log)
LOG_FORMAT=default              # default or json
# LOG_VERBOSE_CONSOLE=false     # If true, WARNING/ERROR use full format (timestamp - logger - level - message)

📖 Pour la référence de configuration complète : Consultez la Référence de configuration ci-dessous pour tous les fournisseurs pris en charge (OpenAI, Azure, Gemini, Bedrock), les variables requises/facultatives et des exemples détaillés.

Étape 3 : Installation de Poetry (recommandé : pipx)

Windows (PowerShell) :

# List available Python versions
py -0p

# Pick any supported Python: 3.10 / 3.11 / 3.12 / 3.13
py -3.12 -m pip install --user -U pipx
py -3.12 -m pipx ensurepath
# Close and reopen terminal (required)
pipx install poetry
poetry --version

macOS / Linux :

# Check your Python version
python3 --version

# Use any supported Python: 3.10 / 3.11 / 3.12 / 3.13
python3 -m pip install --user -U pipx
python3 -m pipx ensurepath
# Restart terminal (required)
pipx install poetry
poetry --version

Étape 4 : Installation des dépendances et configuration

Windows (PowerShell) :

# Pick one supported version you have: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # Force Poetry to use a supported Python version if you have multiple versions installed
poetry install
poetry run vulnhalla-setup

macOS / Linux :

# Pick one supported version you have: 3.10 / 3.11 / 3.12 / 3.13
poetry env use 3.12  # Force Poetry to use a supported Python version if you have multiple versions installed
poetry install
poetry run vulnhalla-setup

Étape 5 : Exécution du pipeline

# Analyze a specific repository, for example:
poetry run vulnhalla redis/redis

# Re-download even if database already exists
poetry run vulnhalla redis/redis --force

# Show help
poetry run vulnhalla --help

Cela va automatiquement :

1. Récupérer les bases de données CodeQL
2. Exécuter les requêtes CodeQL sur toutes les bases de données téléchargées
3. Analyser les résultats avec le LLM et les enregistrer dans output/results/
4. Ouvrir l'interface utilisateur pour parcourir les résultats

Utilisation d'une base de données CodeQL locale

Si vous disposez déjà d'une base de données CodeQL sur disque (par exemple, créée manuellement ou lors d'une exécution précédente), vous pouvez ignorer l'étape de récupération GitHub à l'aide de l'option --local / -l :

Windows (PowerShell) :

poetry run vulnhalla --local C:\path\to\my-codeql-db

macOS / Linux :

poetry run vulnhalla --local /path/to/my-codeql-db

Remarque : L'option --local attend un répertoire de base de données CodeQL, pas un dossier de code source. Vous pouvez vérifier en vous assurant que le dossier contient un fichier codeql-database.yml.

Commandes supplémentaires

# Open UI to view existing results (without running analysis)
poetry run vulnhalla-ui

# Validate configuration: CodeQL, LLM, Logging (without running analysis)
poetry run vulnhalla-validate

# List analyzed repositories and their issue counts
poetry run vulnhalla-list

# Run example pipeline (analyzes videolan/vlc and redis/redis)
poetry run vulnhalla-example

---

🖥️ Interface utilisateur (UI)

Vulnhalla comprend une interface utilisateur complète pour parcourir et explorer les résultats d'analyse.

Lancement de l'interface utilisateur

poetry run vulnhalla-ui

Disposition de l'interface

L'interface affiche une zone supérieure à deux panneaux avec une barre de contrôles en bas :

Zone supérieure (côte à côte, redimensionnable) :

• Panneau gauche (liste des problèmes) :

  • DataTable affichant : ID, Dépôt, Nom du problème, Fichier, Décision du LLM, Décision manuelle
  • Indicateur du nombre de problèmes et du tri
  • Zone de saisie de recherche en bas, mise à jour au fur et à mesure de la saisie (insensible à la casse).

• Panneau droit (détails) :

  • Section Décision du LLM : Affiche la classification du LLM (vrai positif, faux positif ou besoin de plus de données)
  • Section Métadonnées : Nom du problème, dépôt, fichier, ligne, type, nom de la fonction
  • Section Code :
    • 📌 Contexte de code initial (premier extrait de code vu par le LLM)
    • 📥 Code supplémentaire (code demandé par le LLM au cours de la conversation) - affiché uniquement si un code supplémentaire existe
    • Ligne vulnérable surlignée en rouge
  • Section Résumé : Réponse/décision finale du LLM
  • Sélecteur de décision manuelle : Liste déroulante en bas pour définir le verdict manuel (vrai positif, faux positif, incertain ou non défini)

Barre de contrôles inférieure :

• Langage : C (seul langage actuellement pris en charge)
• Filtre par décision du LLM (liste déroulante) : Tous, Vrai positif, Faux positif, Besoin de plus d'informations pour décider
• Boutons d'action : Actualiser, Lancer l'analyse
• Texte d'aide sur les raccourcis clavier

Raccourcis clavier