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

• ↑/↓ - Naviguer dans la liste des problèmes (ligne par ligne)
• Tab / Shift+Tab - Basculer le focus entre les panneaux
• Entrée - Afficher les détails du problème sélectionné
• / - Focus sur la zone de saisie de recherche (panneau gauche)
• Échap - Effacer la recherche et rendre le focus au tableau des problèmes
• r - Recharger les résultats depuis le disque
• [ / ] - Redimensionner les panneaux gauche/droit (ajuster la position du séparateur)
• q - Quitter l'application

Fonctionnalités interactives

Tri des colonnes

• Cliquez sur n'importe quel en-tête de colonne pour trier par cette colonne
• Tri par défaut : par dépôt (croissant), puis par ID (croissant)

Panneaux redimensionnables

• Séparateur déplaçable entre les panneaux Liste des problèmes et Détails
• Souris : Cliquez et faites glisser le séparateur pour redimensionner
• Clavier : Utilisez [ pour déplacer le séparateur vers la gauche, ] pour le déplacer vers la droite
• La position du séparateur est mémorisée pendant la session

📊 Structure de sortie

Après l'exécution du pipeline, les résultats sont organisés dans output/results/<LANG>/<ISSUE_TYPE>/ :

output/results/c/Copy_function_using_source_size/
├── 1_raw.json      # Original CodeQL issue data
├── 1_final.json    # LLM conversation and classification
├── 2_raw.json
├── 2_final.json
└── ...

Chaque *_final.json contient :

• Conversation complète avec le LLM (invites système, messages utilisateur, réponses de l'assistant, appels d'outils)
• Code de statut final (1337 = vulnérable, 1007 = sécurisé, 7331/3713 = plus d'informations nécessaires)

Chaque *_raw.json contient :

• Données originales du problème CodeQL
• Contexte de la fonction
• Chemin de la base de données (inclut les informations org/repo : output/databases/<LANG>/<ORG>/<REPO>)
• Emplacement du problème

🛠 Dépannage

• CodeQL CLI introuvable :
  Définissez CODEQL_PATH dans votre fichier .env avec le chemin complet de votre exécutable CodeQL. Sous Windows : le chemin doit se terminer par .cmd (par exemple, C:\path\to\codeql\codeql.cmd).

• Limites de débit GitHub :
  Définissez GITHUB_TOKEN dans votre fichier .env (obtenez un jeton sur https://github.com/settings/tokens).

• Problèmes liés au LLM :
  Vérifiez que vos clés API dans le fichier .env correspondent à votre fournisseur sélectionné.

• Erreurs d'importation dans l'interface :
  Assurez-vous d'exécuter à partir du répertoire racine du projet, ou utilisez python examples/ui_example.py qui gère la configuration des chemins.

⚙️ Référence de configuration

Variables d'environnement

Toute la configuration est gérée par des variables d'environnement dans votre fichier .env. Voici une référence complète :

Variables requises

Variables requises spécifiques au fournisseur

OpenAI :

Azure OpenAI :

Gemini (Google) :

AWS Bedrock :

* Authentification : utilisez AWS_PROFILE ou AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY (+ AWS_SESSION_TOKEN facultatif pour STS).

Exemple .env pour Bedrock (SSO) :

PROVIDER=bedrock
MODEL=anthropic.claude-3-5-sonnet-20241022-v2:0
AWS_REGION_NAME=us-east-1
AWS_PROFILE=your-profile

⚠️ Prérequis :

• Les identifiants AWS doivent être configurés (SSO, profil IAM ou clés d'accès) avec les autorisations d'invoquer des modèles Bedrock
• Pour les utilisateurs SSO : Exécutez aws sso login --profile your-profile avant d'utiliser Vulnhalla

🔧 Important - Sélection du modèle : Lors de la sélection d'un modèle Bedrock, assurez-vous qu'il prend en charge les appels d'outils/les appels de fonctions (ce n'est pas le cas de tous les modèles Bedrock). L'appel d'outils est un élément clé du flux d'analyse de Vulnhalla ; choisir un modèle compatible fait donc une grande différence en termes de fonctionnalités et de résultats. Les modèles compatibles incluent : Claude 3.x, Mistral ou Cohere Command R.

Variables facultatives

⚠️ Important : N'augmentez pas LLM_TEMPERATURE ou LLM_TOP_P sauf si vous comprenez parfaitement l'impact. Des valeurs plus basses maintiennent le modèle stable et déterministe, ce qui est essentiel pour l'analyse de sécurité. Des valeurs plus élevées peuvent rendre le modèle incohérent, créatif ou lui faire halluciner des résultats.

📝 Remarque : Pour des exemples de configuration supplémentaires, consultez le fichier .env.example à la racine du projet.

Validation de la configuration

Vulnhalla valide votre configuration au démarrage. Si des variables requises sont manquantes ou invalides, vous verrez des messages d'erreur clairs indiquant ce qui doit être corrigé.

Erreurs de validation courantes :

• Clé API manquante pour le fournisseur sélectionné
• Nom de fournisseur invalide (voir PROVIDER pour les valeurs prises en charge)
• Point de terminaison Azure manquant (requis pour le fournisseur Azure)
• Identifiants ou région AWS manquants (requis pour le fournisseur Bedrock)
• Chemin CodeQL invalide (si CODEQL_PATH est défini mais que le fichier n'existe pas)

📝 Codes de statut

Le LLM utilise les codes de statut suivants :

• 1337 : Vulnérabilité de sécurité trouvée (vrai positif)
• 1007 : Le code est sécurisé, aucune vulnérabilité (faux positif)
• 7331 : Plus de code/d'informations nécessaires pour valider la sécurité
• 3713 : Probablement pas un problème de sécurité, mais plus d'informations nécessaires (utilisé avec 7331)

L'interface les mappe ainsi :

• 1337 → "Vrai positif"
• 1007 → "Faux positif"
• 7331 ou 3713 → "Besoin de plus de données"

🔧 Développement

Exécution des tests

Le projet comprend une infrastructure de test de base utilisant pytest :

# Run all tests
poetry run pytest

# Run with verbose output
poetry run pytest -v

La suite de tests comprend des tests de fumée pour vérifier que l'infrastructure de test est correctement configurée.

Vérification de types

Le projet utilise mypy pour la vérification statique des types :

poetry run mypy src

La vérification de types est configurée dans pyproject.toml sous [tool.mypy]. La configuration utilise une base conservatrice avec des dérogations par module pour permettre une adoption progressive.

Dépendances du projet

Les dépendances sont gérées via Poetry dans pyproject.toml :

• requests - Requêtes HTTP pour l'API GitHub
• pySmartDL - Gestionnaire de téléchargement intelligent pour les bases de données CodeQL
• litellm - Interface LLM unifiée prenant en charge plusieurs fournisseurs
• python-dotenv - Gestion des variables d'environnement
• PyYAML - Analyse YAML pour les fichiers de pack CodeQL
• textual - Framework d'interface utilisateur terminal
• pytest - Framework de test (dépendance de développement)
• mypy - Vérificateur de types statique (dépendance de développement)

Requêtes CodeQL

Les requêtes CodeQL sont organisées dans data/queries/<LANG>/ :

• issues/ - Requêtes de détection de problèmes de sécurité
• tools/ - Requêtes auxiliaires (arbres de fonctions, classes, variables globales, macros)

Chaque répertoire contient un fichier qlpack.yml définissant le pack CodeQL.

📄 Licence

Copyright (c) 2025 CyberArk Software Ltd. Tous droits réservés.

Ce dépôt est distribué sous la licence Apache, version 2.0 - voir LICENSE.txt pour plus de détails.

🤝 Contribution

Nous accueillons toutes sortes de contributions sur ce dépôt. Pour savoir comment commencer et pour découvrir nos workflows de développement, consultez notre guide de contribution.

Code de conduite

Veuillez lire et respecter notre Code de conduite. Nous nous engageons à offrir un environnement accueillant et inclusif à tous les contributeurs.

📧 Contact

N'hésitez pas à nous contacter via les issues GitHub si vous avez des demandes de fonctionnalités ou des problèmes liés au projet.